{"record":{"id":"7cde8f0ed1d9d2bc","repo":"vllm-project/vllm","slug":"unexpected-positional-short-argument-token-r-th","errorCode":null,"errorMessage":"Unexpected positional/short argument {token!r}. The converter expects Recipes to emit long-form vLLM serve options.","messagePattern":"Unexpected positional/short argument (.+?)\\. The converter expects Recipes to emit long-form vLLM serve options\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/recipes/recipe_json_to_vllm_config.py","lineNumber":506,"sourceCode":"                raise ValueError(\"-O is missing its value\")\n            merge_value(config, [\"optimization-level\"], coerce(argv[i + 1]))\n            i += 2\n            continue\n\n        # Selected common short aliases.\n        if token in SHORT_ALIASES:\n            if i + 1 >= len(argv):\n                raise ValueError(f\"{token} is missing its value\")\n            merge_value(\n                config,\n                [SHORT_ALIASES[token]],\n                coerce(argv[i + 1]),\n            )\n            i += 2\n            continue\n\n        if not token.startswith(\"--\"):\n            raise ValueError(\n                f\"Unexpected positional/short argument {token!r}. \"\n                \"The converter expects Recipes to emit long-form vLLM serve options.\"\n            )\n\n        # --key=value\n        if \"=\" in token:\n            key, raw_value = token[2:].split(\"=\", 1)\n            merge_value(config, normalize_key(key), coerce(raw_value))\n            i += 1\n            continue\n\n        key = token[2:]\n        i += 1\n\n        # Gather values until the next option. This supports both scalar and\n        # nargs-style vLLM options.\n        raw_values: list[str] = []\n        while i < len(argv) and not is_option_token(argv[i]):","sourceCodeStart":488,"sourceCodeEnd":524,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/tools/recipes/recipe_json_to_vllm_config.py#L488-L524","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["jq '.argv' recipe.json, find the exact token from the error message, and locate its index","Rewrite the offending short flag as its long-form equivalent in the recipe JSON (e.g. -q fp8 -> --quantization fp8)","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","If it's a legitimate new short flag in recipes, add it to SHORT_ALIASES in tools/recipes/recipe_json_to_vllm_config.py"],"exampleFix":"# before\n\"argv\": [\"vllm\",\"serve\",\"m\",\"-q\",\"fp8\"]\n# after\n\"argv\": [\"vllm\",\"serve\",\"m\",\"--quantization\",\"fp8\"]","handlingStrategy":"validation","validationCode":"KNOWN = {\"-O\", \"-tp\", \"-pp\", \"-dp\"}\nfor tok in (str(x) for x in recipe[\"argv\"][3:]):\n    if not tok.startswith(\"--\") and tok not in KNOWN and not tok.startswith(\"-O\"):\n        raise SystemExit(f\"unsupported token {tok!r}; convert to long-form --option\")","typeGuard":"def token_is_supported(tok: str) -> bool:\n    return tok.startswith(\"--\") or tok in {\"-O\", \"-tp\", \"-pp\", \"-dp\"} or (tok.startswith(\"-O\") and len(tok) > 2)","tryCatchPattern":null,"preventionTips":["Emit only long-form options in recipe JSON you control","When new vLLM short flags appear, either expand them to long form or teach SHORT_ALIASES about them"],"tags":["vllm-recipes","argv-parsing","cli","long-form-options"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}