ultralytics/ultralytics · error · SyntaxError

'{a}' is a valid YOLO argument but is missing an '=' sign to

Error message

'{a}' is a valid YOLO argument but is missing an '=' sign to set its value, i.e. try '{a}={DEFAULT_CFG_DICT[a]}'
{CLI_HELP_MSG}

What it means

In the yolo CLI parser, a bare token that matches a default.yaml key is only legal without '=' if the key is boolean (auto-set True), a deprecated precision flag, a task, or a mode. For any other key (e.g. epochs, imgsz, data) a bare token means you forgot '=value', so SyntaxError is raised suggesting 'key=default' plus the CLI help.

Source

Thrown at ultralytics/cfg/__init__.py:1039

                    overrides = {k: val for k, val in YAML.load(checks.check_yaml(v)).items() if k != "cfg"}
                else:
                    overrides[k] = v
            except (NameError, SyntaxError, ValueError, AssertionError) as e:
                check_dict_alignment(full_args_dict, {a: ""}, e)

        elif a in TASKS:
            overrides["task"] = a
        elif a in MODES:
            overrides["mode"] = a
        elif a.lower() in special:
            special[a.lower()]()
            return
        elif a in DEFAULT_CFG_DICT and isinstance(DEFAULT_CFG_DICT[a], bool):
            overrides[a] = True  # auto-True for default bool args, i.e. 'yolo show' sets show=True
        elif a in {"half", "int8"}:
            overrides[a] = True  # deprecated bare precision flags, forwarded to quantize by _handle_deprecation
        elif a in DEFAULT_CFG_DICT:
            raise SyntaxError(
                f"'{colorstr('red', 'bold', a)}' is a valid YOLO argument but is missing an '=' sign "
                f"to set its value, i.e. try '{a}={DEFAULT_CFG_DICT[a]}'\n{CLI_HELP_MSG}"
            )
        else:
            check_dict_alignment(full_args_dict, {a: ""})

    # Check keys
    check_dict_alignment(full_args_dict, overrides)

    # Mode
    mode = overrides.get("mode")
    if mode is None:
        mode = DEFAULT_CFG.mode or "predict"
        LOGGER.warning(f"'mode' argument is missing. Valid modes are {list(MODES)}. Using default 'mode={mode}'.")
    elif mode not in MODES:
        raise ValueError(f"Invalid 'mode={mode}'. Valid modes are {list(MODES)}.\n{CLI_HELP_MSG}")

    # Task

View on GitHub (pinned to 0449ea011c)

Solutions

Attach the value with '=': yolo train epochs=100 imgsz=640.
Remove spaces around '=' in generated command lines.
For boolean keys keep the bare-flag form: yolo predict show (no value needed).
Run yolo settings or yolo help to review accepted keys.

Example fix

# before
yolo predict model=yolo26n.pt source=bus.jpg epochs

# after
yolo predict model=yolo26n.pt source=bus.jpg epochs=100

Defensive patterns

Strategy: validation

Validate before calling

from ultralytics.cfg import DEFAULT_CFG_DICT

def build_cli_tokens(args: dict[str, str]) -> list[str]:
    tokens = []
    for k, v in args.items():
        if isinstance(DEFAULT_CFG_DICT.get(k), bool) and v is True:
            tokens.append(k)          # bare bool flag
        else:
            tokens.append(f"{k}={v}")  # everything else needs '='
    return tokens

Try / catch

try:
    run_yolo_cli(cmd)
except SyntaxError as e:
    if "missing an '=' sign" in str(e):
        fix = re.sub(r"(?<=\s)(\w+)(?=\s|$)", r"\1=", raw_cmd)  # or fix by hand
        raise SystemExit(f"Fix command to: {fix}") from e
    raise

Prevention

Always join key and value with '=' and no spaces when generating yolo commands.
Remember bare tokens are only valid for bool keys (yolo predict show).
Test generated CLI strings with yolo help or a dry parse before executing.

When it happens

Trigger: `yolo predict model=yolo26n.pt epochs` (missing =100), `yolo train data` , `yolo val imgsz` — any non-bool cfg key given as a standalone word on the command line. Works fine for bool keys: `yolo predict show` sets show=True.

Common situations: Shell quoting that splits on '=' (e.g. writing yolo train epochs = 100 with spaces); muscle memory from tools where flags and values are separate arguments; scripts concatenating args with spaces around '=' (merge_equals_args handles some but not all splits — only in CLI entrypoint).

Related errors

AI-assisted analysis of ultralytics/ultralytics@0449ea011c (2026-08-15). Data as JSON: /api/errors/e6867bafa8b69f73. Report an issue: GitHub.