locustio/locust · error · ValueError

Invalid time span format

Error message

Invalid time span format

What it means

parse_timespan converts a human string like '3h30m' into seconds. If the argument is empty or None (falsy), there is nothing to parse, so it raises this ValueError immediately before regex matching. The `--run-time`/`swarm` option relies on it.

Source

Thrown at locust/util/timespan.py:11

import re
from datetime import timedelta


def parse_timespan(time_str) -> int:
    """
    Parse a string representing a time span and return the number of seconds.
    Valid formats are: 20, 20s, 3m, 2h, 1h20m, 3h30m10s, etc.
    """
    if not time_str:
        raise ValueError("Invalid time span format")

    if re.match(r"^\d+$", time_str):
        # if an int is specified we assume they want seconds
        return int(time_str)

    timespan_regex = re.compile(r"((?P<hours>\d+?)h)?((?P<minutes>\d+?)m)?((?P<seconds>\d+?)s)?")
    parts = timespan_regex.match(time_str)
    if not parts or parts.group(0) != time_str:
        raise ValueError("Invalid time span format. Valid formats: 20, 20s, 3m, 2h, 1h20m, 3h30m10s, etc.")
    time_params = {name: int(value) for name, value in parts.groupdict().items() if value}
    if not time_params:
        raise ValueError("Invalid time span format. Valid formats: 20, 20s, 3m, 2h, 1h20m, 3h30m10s, etc.")
    return int(timedelta(**time_params).total_seconds())

View on GitHub (pinned to f391a716e1)

Solutions

1. Ensure the run-time value is set and non-empty before passing it (e.g. `run_time or '5m'` default)
2. Validate the env/config value at startup and fail with a clear message
3. If an unlimited run is intended, omit the --run-time flag entirely instead of passing an empty string

Example fix

# before
runner.environment.create_locals(); runner.swarm(args.host, run_time=os.environ.get('RUN_TIME',''))

# after
run_time = os.environ.get('RUN_TIME')
if run_time:
    runner.swarm(args.host, run_time=run_time)

def validate_run_time(v):
    if not v:
        raise ValueError('--run-time must be a non-empty string like 20, 20s, 3m, 2h, 1h20m')
    return v

try:
    seconds = parse_timespan(args.run_time)
except ValueError:
    log.error('--run-time is empty or missing; e.g. --run-time=5m')
    sys.exit(2)

When it happens

Trigger: Calling parse_timespan('') or parse_timespan(None); passing --run-time with an empty value, e.g. `locust --run-time=` or swarm(run_time="") programmatically.

Common situations: CLI flag configured from an empty environment variable or unfilled config file value; programmatic swarm() calls where run_time was never defaulted.

Related errors

• Invalid time span format. Valid formats: 20, 20s, 3m, 2h, 1h
• Unrecognized task type in user
• The following user classes have the same class name: {}
• No tag name was supplied

AI-assisted analysis of locustio/locust@f391a716e1 (2026-08-29). Data as JSON: /api/errors/67f8aa1dc7e73067. Report an issue: GitHub.