sgl-project/sglang · error · ComponentCheckpointUnsupportedError

f"Cannot parse checkpoint quantization for {component_name!r

Error message

f"Cannot parse checkpoint quantization for {component_name!r}: {error}"

What it means

uses_native_transformers_bnb4 inspects a component's serialized quantization metadata via resolve_checkpoint_quant_spec. If that parsing itself raises TypeError or ValueError (malformed quantization_config), it wraps it in ComponentCheckpointUnsupportedError with this message.

Source

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

)

logger = init_logger(__name__)


class ComponentCheckpointUnsupportedError(ValueError):
    """A component checkpoint is unsupported and must not use native fallback."""


class NativeComponentLoaderRequired(RuntimeError):
    """The customized loader must defer to the native library loader."""


def uses_native_transformers_bnb4(config: object, component_name: str) -> bool:
    """Validate a serialized BnB4 checkpoint owned by Transformers."""
    try:
        quant_spec = resolve_checkpoint_quant_spec(config)
    except (TypeError, ValueError) as error:
        raise ComponentCheckpointUnsupportedError(
            f"Cannot parse checkpoint quantization for {component_name!r}: {error}"
        ) from error
    if quant_spec is None or quant_spec.declared_method != "bitsandbytes":
        return False
    if quant_spec.source != "quantization_config":
        raise ComponentCheckpointUnsupportedError(
            f"Transformers-managed {component_name!r} quantization requires "
            "a top-level quantization_config; "
            f"got metadata from {quant_spec.source!r}"
        )

    load_in_4bit = quant_spec.config.get(
        "load_in_4bit", quant_spec.config.get("_load_in_4bit")
    )
    load_in_8bit = quant_spec.config.get(
        "load_in_8bit", quant_spec.config.get("_load_in_8bit", False)
    )
    if load_in_4bit is not True or load_in_8bit is True:

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect component config's quantization_config field and fix its structure (must be a parseable dict)
2. Re-download the component checkpoint in case config.json is truncated/corrupt
3. If the checkpoint genuinely uses an unsupported quant metadata layout, load it with an unquantized export instead

from sglang.srt.quantization import resolve_checkpoint_quant_spec

try:
    resolve_checkpoint_quant_spec(config)
except (TypeError, ValueError):
    config.pop("quantization_config", None)  # or repair the field

except ComponentCheckpointUnsupportedError as e:
    if "Cannot parse checkpoint quantization" in str(e):
        logger.warning("malformed quant metadata on %s; using plain checkpoint", name)

When it happens

Trigger: A component config whose quantization_config is of an unexpected type (e.g. a list instead of dict) or contains invalid fields, causing resolve_checkpoint_quant_spec to raise; called during load_native or the bnb4 delegation path.

Common situations: Hand-edited or partially downloaded config.json with a broken quantization_config; checkpoints from tools that serialize quantization metadata in a non-standard shape; version drift in the quant spec schema.

Related errors

• f"Transformers-managed {component_name!r} quantization requi
• {component_name!r} does not support an explicit quantization
• Cannot parse checkpoint quantization metadata for {component
• The quantization method `{quantization}` is already exists.
• The quantization config must be a subclass of `QuantizationC

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