sgl-project/sglang · error · ComponentCheckpointUnsupportedError

{component_name!r} checkpoint declares quantization metadata

Error message

{component_name!r} checkpoint declares quantization metadata in {quant_spec.source} (quant_method={method!r}), which its current plain state-dict materializer cannot restore.

What it means

For components materialized from a plain state dict (no quantization support), any non-None quant spec is rejected: even an unspecified quant_method in any source field raises ComponentCheckpointUnsupportedError, failing closed rather than silently loading quantized weights as fp16.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/component_loaders/component_loader.py:526

class PlainStateDictComponentLoader(ComponentLoader):
    """Base for native loaders whose current materializer expects plain weights."""

    @staticmethod
    def ensure_plain_state_dict_checkpoint(config: object, component_name: str) -> None:
        try:
            quant_spec = resolve_checkpoint_quant_spec(config)
        except (TypeError, ValueError) as error:
            raise ComponentCheckpointUnsupportedError(
                f"Cannot parse checkpoint quantization metadata for "
                f"{component_name!r}: {error}"
            ) from error
        if quant_spec is None:
            return

        method = quant_spec.declared_method or "unspecified"
        raise ComponentCheckpointUnsupportedError(
            f"{component_name!r} checkpoint declares quantization metadata in "
            f"{quant_spec.source} (quant_method={method!r}), which its current "
            "plain state-dict materializer cannot restore."
        )

    def load_component_config(
        self, component_model_path: str, component_name: str
    ) -> dict[str, Any]:
        config = get_diffusers_component_config(component_path=component_model_path)
        self.ensure_plain_state_dict_checkpoint(config, component_name)
        return config

    def resolve_component_weights_path(
        self,
        component_model_path: str,
        server_args: ServerArgs,
        component_name: str,
    ) -> str:

View on GitHub (pinned to 0132848349)

Solutions

1. Download the unquantized (fp16/bf16) variant of that component
2. Use a loader that supports the declared quantization format for that component
3. If the metadata is spurious (checkpoint is actually plain), remove the quantization fields from its config.json

qc = {k: v for k, v in config.items() if 'quant' in k.lower()}
assert not qc, f"plain state-dict loader cannot restore quantized metadata: {qc}"

When it happens

Trigger: A component checkpoint that declares quantization metadata anywhere (top-level quantization_config, hf_quantifier, or other sources) is loaded through a loader whose materializer is a plain state-dict loader (no quant restore support).

Common situations: Downloading an fp8/bnb-quantized variant of a component while the code path only supports plain fp16/bf16 state dicts; serving a mixed checkpoint repo where one component is quantized; version skew where a component became quantized upstream.

Related errors

• Cannot parse checkpoint quantization metadata for {component
• f"Adapter weights at '{component_weights_path}' do not match
• f"Cannot parse checkpoint quantization for {component_name!r
• f"Transformers-managed {component_name!r} quantization requi
• {component_name!r} does not support an explicit quantization

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/a57328d33a8e9b31. Report an issue: GitHub.