vllm-project/vllm · error · ValueError

Unexpected positional/short argument {token!r}. The converte

Error message

Unexpected positional/short argument {token!r}. The converter expects Recipes to emit long-form vLLM serve options.

What it means

After the -O forms and the three short aliases (-tp/-pp/-dp) are handled, argv_to_config() only accepts tokens starting with '--' (long-form options, optionally --key=value). Any other token — a positional argument or an unrecognized short flag like -q, -c, -e — is rejected, because the converter's YAML grammar only models long-form vLLM serve options.

Source

Thrown at tools/recipes/recipe_json_to_vllm_config.py:506

                raise ValueError("-O is missing its value")
            merge_value(config, ["optimization-level"], coerce(argv[i + 1]))
            i += 2
            continue

        # Selected common short aliases.
        if token in SHORT_ALIASES:
            if i + 1 >= len(argv):
                raise ValueError(f"{token} is missing its value")
            merge_value(
                config,
                [SHORT_ALIASES[token]],
                coerce(argv[i + 1]),
            )
            i += 2
            continue

        if not token.startswith("--"):
            raise ValueError(
                f"Unexpected positional/short argument {token!r}. "
                "The converter expects Recipes to emit long-form vLLM serve options."
            )

        # --key=value
        if "=" in token:
            key, raw_value = token[2:].split("=", 1)
            merge_value(config, normalize_key(key), coerce(raw_value))
            i += 1
            continue

        key = token[2:]
        i += 1

        # Gather values until the next option. This supports both scalar and
        # nargs-style vLLM options.
        raw_values: list[str] = []
        while i < len(argv) and not is_option_token(argv[i]):

View on GitHub (pinned to c794754062)

Solutions

1. jq '.argv' recipe.json, find the exact token from the error message, and locate its index
2. Rewrite the offending short flag as its long-form equivalent in the recipe JSON (e.g. -q fp8 -> --quantization fp8)
3. If the token is truly positional with no YAML equivalent, remove it from the recipe and set it via env.sh or a wrapper script
4. If it's a legitimate new short flag in recipes, add it to SHORT_ALIASES in tools/recipes/recipe_json_to_vllm_config.py

Example fix

# before
"argv": ["vllm","serve","m","-q","fp8"]
# after
"argv": ["vllm","serve","m","--quantization","fp8"]

KNOWN = {"-O", "-tp", "-pp", "-dp"}
for tok in (str(x) for x in recipe["argv"][3:]):
    if not tok.startswith("--") and tok not in KNOWN and not tok.startswith("-O"):
        raise SystemExit(f"unsupported token {tok!r}; convert to long-form --option")

def token_is_supported(tok: str) -> bool:
    return tok.startswith("--") or tok in {"-O", "-tp", "-pp", "-dp"} or (tok.startswith("-O") and len(tok) > 2)

When it happens

Trigger: Recipe argv containing short flags outside the alias table (e.g. '--dtype bfloat16 -q fp8' or a stray positional like a port number whose flag got dropped); a tokenizer/recipe bug splitting '--key value' incorrectly leaving a bare value token.

Common situations: New vLLM short flags added to recipes that the converter's SHORT_ALIASES doesn't know; hand-written argv mixing styles; positional serve args (e.g. a scheduler plugin) that genuinely have no config.yml equivalent.

Related errors

• Expected recipe argv to start with: ['vllm', 'serve', MODEL,
• Expected model after 'vllm serve', got {model!r}
• Cannot merge nested option {'.'.join(path)!r}: {part!r} is a
• -O is missing its value
• {token} is missing its value

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/7cde8f0ed1d9d2bc. Report an issue: GitHub.