{"record":{"id":"cc7276c2542d1705","repo":"sgl-project/sglang","slug":"unknown-kv-cache-quantization-method-name-av","errorCode":null,"errorMessage":"Unknown KV cache quantization method: '{name}'. Available: {list(KV_CACHE_QUANT_REGISTRY)}","messagePattern":"Unknown KV cache quantization method: '(.+?)'\\. Available: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/layers/quantization/fp4_kv_cache_quant_method.py","lineNumber":833,"sourceCode":"        raise ValueError(\n            \"--kv-cache-dtype=fp4_e2m1 is deprecated. \"\n            \"Use --kv-cache-dtype=fp4_mx_block16.\"\n        )\n    if kv_cache_dtype == \"mxfp4\":\n        raise ValueError(\n            \"--kv-cache-dtype=mxfp4 is reserved for true MXFP4 block-size-32 \"\n            \"semantics. Use --kv-cache-dtype=fp4_mx_block16 for the current \"\n            \"block-size-16 FP4 KV recipe.\"\n        )\n    if kv_cache_dtype in KV_CACHE_QUANT_REGISTRY:\n        return kv_cache_dtype\n    return None\n\n\ndef get_kv_cache_quant_method(name: str, **kwargs) -> KVCacheQuantMethodBase:\n    \"\"\"Instantiate a KVCacheQuantMethodBase by internal method name.\"\"\"\n    if name not in KV_CACHE_QUANT_REGISTRY:\n        raise ValueError(\n            f\"Unknown KV cache quantization method: '{name}'. \"\n            f\"Available: {list(KV_CACHE_QUANT_REGISTRY)}\"\n        )\n    return KV_CACHE_QUANT_REGISTRY[name](**kwargs)\n","sourceCodeStart":815,"sourceCodeEnd":838,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/layers/quantization/fp4_kv_cache_quant_method.py#L815-L838","documentation":"Raised by get_kv_cache_quant_method when the requested KV cache quantization method name is not present in KV_CACHE_QUANT_REGISTRY. The registry only contains methods that have been explicitly registered for KV cache quantization (e.g. fp8 variants), so any unrecognized quant string from the checkpoint/server config fails fast. This is a factory lookup error, not a runtime kernel error.","triggerScenarios":"Calling get_kv_cache_quant_method(name, **kwargs) with a name not in KV_CACHE_QUANT_REGISTRY — typically indirectly by launching a server or model whose quantization_config specifies an unsupported kv cache quant algo (e.g. 'int8', 'awq', or a typo like 'fp8_e5m2' when only fp8 methods are registered).","commonSituations":"Using a checkpoint with a quantization_config kv-cache method SGLang does not support; typo in --kv-cache-dtype or quant config; new/renamed method names after a version upgrade; passing a weight-quant method name where a KV-quant method is expected.","solutions":["Check the registry contents at runtime: from sglang.srt.layers.quantization.fp4_kv_cache_quant_method import KV_CACHE_QUANT_REGISTRY; print(list(KV_CACHE_QUANT_REGISTRY)) and use one of those names","Fix the quantization_config in the model's config.json (quant_method for kv cache) to a supported method such as 'fp8'","Upgrade SGLang to a version that registers the method you need","If you implemented a new KV quant method, decorate/register it in KV_CACHE_QUANT_REGISTRY"],"exampleFix":"// before\nmethod = get_kv_cache_quant_method(\"int8\")  # ValueError\n// after\nfrom sglang.srt.layers.quantization.fp4_kv_cache_quant_method import KV_CACHE_QUANT_REGISTRY\nname = \"fp8\"\nassert name in KV_CACHE_QUANT_REGISTRY, f\"pick from {list(KV_CACHE_QUANT_REGISTRY)}\"\nmethod = get_kv_cache_quant_method(name)","handlingStrategy":"validation","validationCode":"from sglang.srt.layers.quantization.fp4_kv_cache_quant_method import KV_CACHE_QUANT_REGISTRY, get_kv_cache_quant_method\nname = cfg.quant_method\nif name not in KV_CACHE_QUANT_REGISTRY:\n    raise SystemExit(f\"unsupported kv quant {name}; pick from {list(KV_CACHE_QUANT_REGISTRY)}\")\nmethod = get_kv_cache_quant_method(name)","typeGuard":"def is_supported_kv_quant(name: str) -> bool:\n    from sglang.srt.layers.quantization.fp4_kv_cache_quant_method import KV_CACHE_QUANT_REGISTRY\n    return name in KV_CACHE_QUANT_REGISTRY","tryCatchPattern":"try:\n    m = get_kv_cache_quant_method(name)\nexcept ValueError as e:\n    logger.warning(\"falling back to fp8 kv quant: %s\", e)\n    m = get_kv_cache_quant_method(\"fp8\")","preventionTips":["Validate quant method names against KV_CACHE_QUANT_REGISTRY before constructing configs","Pin SGLang versions in CI to avoid registry churn","Log the registry contents in startup diagnostics"],"tags":["quantization","kv-cache","config-validation","registry"],"backgroundTag":"unsupported-quantization-method","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}