sgl-project/sglang · error · TypeError

{source} must be a mapping or expose to_dict(), got {type(va

Error message

{source} must be a mapping or expose to_dict(), got {type(value).__name__}

What it means

_to_metadata_dict accepts either a Mapping or an object with a callable to_dict() that returns a Mapping, and raises TypeError otherwise when normalizing quantization metadata. It is used by resolve_checkpoint_quant_spec to read HF quantization_config style metadata. The error means the value passed as quant metadata is of an unexpected type (e.g. a string, list, or object whose to_dict returns non-mapping).

Source

Thrown at python/sglang/srt/model_loader/checkpoint_quantization.py:55

def _get_field(config: object, name: str) -> Any:
    if isinstance(config, Mapping):
        return config.get(name)
    return getattr(config, name, None)


def _to_metadata_dict(value: object, source: QuantMetadataSource) -> dict[str, Any]:
    if isinstance(value, Mapping):
        return deepcopy(dict(value))

    to_dict = getattr(value, "to_dict", None)
    if callable(to_dict):
        metadata = to_dict()
        if isinstance(metadata, Mapping):
            return deepcopy(dict(metadata))

    raise TypeError(
        f"{source} must be a mapping or expose to_dict(), "
        f"got {type(value).__name__}"
    )


def _select_hf_quant_metadata(
    hf_config: object,
) -> tuple[QuantMetadataSource, object] | None:
    value = _get_field(hf_config, "quantization_config")
    if value is not None:
        return "quantization_config", value

    text_config = _get_field(hf_config, "text_config")
    value = _get_field(text_config, "quantization_config")
    if value is not None:
        return "text_config.quantization_config", value

    value = _get_field(hf_config, "compression_config")

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a plain dict (or Mapping) as the quant metadata value
2. If using a config object, ensure it exposes to_dict() returning a dict
3. Normalize earlier: json.loads / dict(...) before calling resolve_checkpoint_quant_spec
4. Inspect type(value) in the error message to find which field is malformed and fix its producer

Example fix

// before
spec = resolve_checkpoint_quant_spec(quant_config=model_config.hf_config.quantization_config_string)
// after
import json
spec = resolve_checkpoint_quant_spec(quant_config=json.loads(model_config.hf_config.quantization_config_string))

from collections.abc import Mapping

def as_quant_metadata(value, source='quant_config'):
    if isinstance(value, Mapping):
        return dict(value)
    to_dict = getattr(value, 'to_dict', None)
    if callable(to_dict):
        out = to_dict()
        if isinstance(out, Mapping):
            return dict(out)
    raise TypeError(f'{source} must be a mapping or expose to_dict(), got {type(value).__name__}')

def is_quant_metadata(value) -> bool:
    if isinstance(value, Mapping):
        return True
    to_dict = getattr(value, 'to_dict', None)
    return callable(to_dict) and isinstance(to_dict(), Mapping)

When it happens

Trigger: Calling resolve_checkpoint_quant_spec with quant_config that is neither a dict/Mapping nor exposes to_dict() returning a Mapping; e.g. passing hf_quant_config.quantization_config as a raw JSON string or a list, or a dataclass whose to_dict returns None.

Common situations: Custom or non-standard HuggingFace quantization_config formats, checkpoints with quant config stored as a string, or caller code passing model_config attributes directly without dict conversion.

Related errors

• The quantization config must be a subclass of `QuantizationC
• SGLang diffusion currently supports AutoRound auto_gptq chec
• AutoRound fused module {target!r} has inconsistent shard con
• Parameter {param_name} not found in the model.
• Unsupported quantized embedding marker for {prefix!r}: {mark

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