{"record":{"id":"1306b0790954bced","repo":"vllm-project/vllm","slug":"unknown-quantization-name-v-r-expected-one-of","errorCode":null,"errorMessage":"unknown quantization name {v!r}; expected one of {sorted(QUANT_KEY_NAMES)}","messagePattern":"unknown quantization name (.+?); expected one of (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/quantization.py","lineNumber":47,"sourceCode":"    \"fp8_per_token\": kFp8DynamicTokenSym,\n    \"fp8_per_channel_static\": kFp8StaticChannelSym,\n    \"fp8_per_block_static\": kFp8Static128BlockSym,\n    \"fp8_per_block_dynamic\": kFp8Dynamic128Sym,\n    \"mxfp8\": kMxfp8Dynamic,\n    \"mxfp4\": kMxfp4Dynamic,\n    \"int8_per_channel_static\": kInt8StaticChannelSym,\n}\n\n\ndef _coerce_quant_key(v: Any) -> QuantKey | None:\n    if v is None or isinstance(v, QuantKey):\n        return v\n    if not isinstance(v, str):\n        raise TypeError(f\"expected str or QuantKey, got {type(v).__name__}\")\n    try:\n        return QUANT_KEY_NAMES[v]\n    except KeyError:\n        raise ValueError(\n            f\"unknown quantization name {v!r}; \"\n            f\"expected one of {sorted(QUANT_KEY_NAMES)}\"\n        ) from None\n\n\n# Stop pydantic from introspecting QuantKey: it transitively contains a\n# NamedTuple with `ClassVar[GroupShape]` declarations that pydantic refuses.\nQuantKeyField = Annotated[\n    QuantKey | None,\n    GetPydanticSchema(\n        lambda _src, _handler: core_schema.no_info_plain_validator_function(\n            _coerce_quant_key\n        )\n    ),\n]\n\n\n@config","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/quantization.py#L29-L65","documentation":"Raised by _coerce_quant_key (a pydantic plain validator behind QuantKeyField) when a quantization spec string does not match any key in the QUANT_KEY_NAMES registry. The string is looked up in a fixed mapping of CLI-style quantization names to QuantKey singletons; a miss means the name is misspelled, removed, or not a registered per-layer quant key. The message lists all accepted names.","triggerScenarios":"Passing a string like quantization_config={'linear': 'fp8_staict_tensor'} (typo) to QuantizationConfigArgs, or using a name that is an online CLI shorthand (e.g. 'fp8_per_tensor') where a QuantKey name is expected, or a name that only exists in an older/newer vLLM revision.","commonSituations":"Typos in quantization-config YAML/JSON; copy-pasting a --quantization shorthand into --quantization-config; version drift after QUANT_KEY_NAMES was renamed or entries were added/removed.","solutions":["Copy the accepted list straight from the error message and use one of those exact strings","If you meant a whole-preset, use a --quantization online shorthand (e.g. fp8_per_tensor) instead of a per-field QuantKey name","Pass a QuantKey instance instead of a string when constructing configs programmatically","If the name should exist, check you are on the vLLM version that registers it (grep QUANT_KEY_NAMES in vllm/config/quantization.py)"],"exampleFix":"# before\nargs = QuantizationConfigArgs(linear='fp8_per_tensor')\n\n# after\nargs = QuantizationConfigArgs(linear='fp8_static_tensor_sym')  # exact QUANT_KEY_NAMES key","handlingStrategy":"validation","validationCode":"from vllm.config.quantization import QUANT_KEY_NAMES\n\ndef valid_quant_name(name: str) -> bool:\n    return name in QUANT_KEY_NAMES","typeGuard":"from vllm.config.quantization import QUANT_KEY_NAMES, QuantKey\n\ndef is_quant_key_name(v: object) -> bool:\n    return isinstance(v, str) and v in QUANT_KEY_NAMES or isinstance(v, QuantKey)","tryCatchPattern":"try:\n    QuantizationConfigArgs(linear=name)\nexcept ValueError as e:\n    if 'unknown quantization name' in str(e):\n        raise SystemExit(f'bad quant name {name!r}; valid: {sorted(QUANT_KEY_NAMES)}') from e\n    raise","preventionTips":["Validate names against QUANT_KEY_NAMES before building configs","Pin the vLLM version whose QUANT_KEY_NAMES you developed against","Prefer QuantKey constants over hand-typed strings in code"],"tags":["quantization","config","validation","pydantic"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}