vllm-project/vllm · error · ValueError

Unexpected positional/short argument

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.

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 model after 'vllm serve', got
• Expected recipe argv to start with: ['vllm', 'serve'…
• Cannot merge nested option
• -O is missing its value
• Recipe JSON does not contain an `argv` field

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

Appendix: 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)