{"record":{"id":"b2b8f1712573157c","repo":"sgl-project/sglang","slug":"invalid-quanto-quantization-map-base64","errorCode":null,"errorMessage":"Invalid Quanto quantization_map_base64","messagePattern":"Invalid Quanto quantization_map_base64","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/quantization/configs/quanto_int8_config.py","lineNumber":101,"sourceCode":"    file_path: str,\n    param_name_mapper: Callable[[str], str] | None = None,\n) -> QuantoInt8Config | None:\n    \"\"\"Validate a self-describing Quanto qint8 safetensors checkpoint.\"\"\"\n\n    with safe_open(file_path, framework=\"pt\", device=\"cpu\") as checkpoint:\n        metadata = checkpoint.metadata() or {}\n        if metadata.get(\"quantization_format\") != \"quanto\":\n            return None\n\n        encoded_map = metadata.get(\"quantization_map_base64\")\n        if encoded_map is None:\n            raise ValueError(\"Quanto checkpoint is missing quantization_map_base64\")\n        try:\n            quantization_map = json.loads(\n                base64.b64decode(encoded_map, validate=True).decode(\"utf-8\")\n            )\n        except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as error:\n            raise ValueError(\"Invalid Quanto quantization_map_base64\") from error\n        if not isinstance(quantization_map, dict) or not quantization_map:\n            raise ValueError(\"Quanto quantization map must be a non-empty object\")\n        if not all(\n            isinstance(prefix, str) and isinstance(spec, dict)\n            for prefix, spec in quantization_map.items()\n        ):\n            raise ValueError(\"Quanto quantization map entries must be named objects\")\n\n        checkpoint_keys = set(checkpoint.keys())\n        data_suffix = \".weight._data\"\n        data_prefixes = {\n            name.removesuffix(data_suffix)\n            for name in checkpoint_keys\n            if name.endswith(data_suffix)\n        }\n        map_prefixes = set(quantization_map)\n        if data_prefixes != map_prefixes:\n            missing_map = data_prefixes - map_prefixes","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/quantization/configs/quanto_int8_config.py#L83-L119","documentation":"The quantization_map_base64 metadata field failed to decode: it is not valid base64, not valid UTF-8 after decoding, or the decoded text is not JSON. The decode+parse is wrapped so any of these corruption modes surfaces as this single error.","triggerScenarios":"A quantization_map_base64 header containing characters outside the base64 alphabet (validate=True rejects them), stray whitespace/newlines, or double-encoded JSON.","commonSituations":"Metadata edited or re-serialized by a converter tool; base64 with padding stripped; JSON that was urlsafe-base64 encoded instead of standard base64.","solutions":["Regenerate the map with base64.b64encode(json.dumps(map).encode()).decode()","Verify round-trip: json.loads(base64.b64decode(value, validate=True)) succeeds before writing","Check for urlsafe vs standard base64 and transcribe '-'/'_' to '+'/'/' if needed"],"exampleFix":"# before (corrupted / non-base64)\nmetadata[\"quantization_map_base64\"] = \"{not base64!!}\"\n\n# after\nimport base64, json\nmetadata[\"quantization_map_base64\"] = base64.b64encode(\n    json.dumps({\"encoder.layers.0\": {\"weights\": \"int8\"}}).encode(\"utf-8\")\n).decode(\"ascii\")","handlingStrategy":"validation","validationCode":"import base64, json\ndef map_decodes(b64: str) -> bool:\n    try:\n        json.loads(base64.b64decode(b64, validate=True).decode(\"utf-8\"))\n        return True\n    except Exception:\n        return False","typeGuard":"def is_valid_quanto_map_b64(value: object) -> bool:\n    return (\n        isinstance(value, str)\n        and json.loads(base64.b64decode(value, validate=True).decode(\"utf-8\")) is not None\n    ) if isinstance(value, str) and _decodes(value) else False","tryCatchPattern":"try:\n    cfg = inspect_quanto_int8_checkpoint(ckpt)\nexcept ValueError as e:\n    if \"quantization_map_base64\" in str(e):\n        raise RuntimeError(\"corrupt quanto metadata; re-export checkpoint\") from e\n    raise","preventionTips":["Always write maps via base64.b64encode(json.dumps(m).encode()).decode()","Validate the round-trip immediately after writing metadata"],"tags":["quantization","quanto","base64","json","checkpoint-metadata"],"backgroundTag":"invalid-serialized-metadata","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}