sgl-project/sglang · error · ComponentCheckpointUnsupportedError

{component_name!r} manages its own checkpoint quantization a

Error message

{component_name!r} manages its own checkpoint quantization and does not support an online quantization override

What it means

ComponentCheckpointUnsupportedError raised when an explicit online quantization override is requested for a model class that sets manages_checkpoint_quantization = True. Such models (e.g. Ideogram with bitsandbytes) parse quantization metadata and attach quant states themselves; the generic lifecycle would process weights twice, so overrides are rejected.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/component_loaders/text_encoder_loader.py:262

                param_name_mapper=name_mapper,
            )
            quant_config = resolve_comfy_checkpoint_quantization(markers)
    return quant_config


def _configure_encoder_quantization(
    model_config: EncoderConfig,
    model_cls: type[nn.Module],
    component_config: dict,
    component_model_path: str,
    component_weights_path: str,
    component_name: str,
    explicit_quantization: str | None = None,
    ignored_layers: list[str] | None = None,
) -> None:
    if getattr(model_cls, "manages_checkpoint_quantization", False):
        if explicit_quantization is not None:
            raise ComponentCheckpointUnsupportedError(
                f"{component_name!r} manages its own checkpoint quantization and "
                "does not support an online quantization override"
            )
        # Preserve model-owned formats such as Ideogram's bitsandbytes state.
        # Those models parse metadata, construct layers, and attach quant states
        # themselves; running the generic lifecycle as well would process twice.
        return

    _delegate_standard_bnb4_to_transformers(
        component_config,
        component_name,
    )
    try:
        quant_config = _get_encoder_quant_config(
            component_config,
            component_model_path,
            component_weights_path,
            model_cls,

View on GitHub (pinned to 0132848349)

Solutions

1. Drop the explicit_quantization argument for this component; let the model manage its own checkpoint quantization
2. Scope online quantization overrides to components that support them (e.g. via per-component config)
3. If you truly need a different quantization, use a checkpoint already quantized in that format

Example fix

# before
load_customized(..., explicit_quantization="fp8")  # Ideogram encoder

# after
load_customized(..., explicit_quantization=None)

if explicit_quantization is not None and getattr(model_cls, "manages_checkpoint_quantization", False):
    explicit_quantization = None  # or raise early with a clear message

def supports_online_quant(model_cls) -> bool:
    return not getattr(model_cls, "manages_checkpoint_quantization", False)

When it happens

Trigger: Calling _configure_encoder_quantization (via load_customized) with explicit_quantization set (e.g. "fp8"/"int8") on a model_cls whose class attribute manages_checkpoint_quantization is True, such as an Ideogram text encoder.

Common situations: Applying a pipeline-wide --quantization flag to all components including ones that self-manage quantization; assuming every encoder accepts online quantization after it worked for CLIP.

Related errors

• {component_name!r} already declares checkpoint quantization;
• Online quantization {explicit_quantization!r} is not support
• Online quantization for {component_name!r} requires an in-tr
• GGUFConfig must be constructed from a GGUF checkpoint
• The SRT encoder checkpoint adapter supports only serialized

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