sgl-project/sglang · error · ValueError

f"Adapter weights at '{component_weights_path}' do not match

Error message

f"Adapter weights at '{component_weights_path}' do not match the instantiated {cls_name}. Missing: {sorted(missing)}. Unexpected: {sorted(unexpected)}. This usually means the adapter config or its weight-name mapping is wrong."

What it means

After loading the adapter state dict with strict=False, the loader checks missing and unexpected keys. A checkpoint that carries neither the shared text_proj_in nor the per-modality projections — or has extra/foreign keys — produces this ValueError, indicating the adapter config or weight-name mapping is wrong.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/component_loaders/adapter_loader.py:89

            server_args, component_name, precision_attr="dit_precision"
        )

        config_cls = self._CONFIG_CLASSES[component_name]
        with set_default_torch_dtype(default_dtype), skip_init_modules():
            adapter_cfg = config_cls()
            adapter_cfg.update_model_arch(config)
            model = model_cls(adapter_cfg).to(device=target_device, dtype=default_dtype)

        loaded = load_safetensors_state_dict(component_weights_path)
        mapping = adapter_cfg.arch_config.param_names_mapping
        loaded = {_remap_connector_key(k, mapping): v for k, v in loaded.items()}

        missing, unexpected = model.load_state_dict(loaded, strict=False)
        # `strict=False` because a checkpoint carries either the shared
        # `text_proj_in` or the per-modality projections, never both. Anything
        # else uninitialized would surface later as garbage embeddings.
        if missing or unexpected:
            raise ValueError(
                f"Adapter weights at '{component_weights_path}' do not match the "
                f"instantiated {cls_name}. Missing: {sorted(missing)}. "
                f"Unexpected: {sorted(unexpected)}. This usually means the "
                "adapter config or its weight-name mapping is wrong."
            )

        return model


def _remap_connector_key(key: str, param_names_mapping: dict[str, str]) -> str:
    for pattern, replacement in param_names_mapping.items():
        key, replaced = re.subn(pattern, replacement, key)
        if replaced:
            break
    return key

View on GitHub (pinned to 0132848349)

Solutions

1. Verify config.json's _class_name matches the checkpoint's actual architecture (re-download the matching adapter)
2. Regenerate/re-download the adapter weights so they match the instantiated class
3. If developing a new adapter variant, extend the weight-name mapping so checkpoint keys are translated to model keys

import json, torch

expected = set(model.state_dict())
ckpt_keys = set(torch.load(weights_file, map_location='cpu').keys())
# only projection weights may legitimately differ
non_proj = expected.symmetric_difference(ckpt_keys) - {'text_proj_in.weight', 'text_proj_in.bias'}
assert not non_proj, f"key mismatch: {non_proj}"

try:
    loader.load_customized(path, server_args, name)
except ValueError as e:
    if "do not match" in str(e):
        # checkpoint/config architecture mismatch: fetch matching revision
        download_matching_revision(path, revision)
    raise

When it happens

Trigger: Loading an adapter checkpoint whose keys don't line up with the instantiated class: keys missing entirely (missing non-projection weights) or extra keys not in the model (unexpected), e.g. a checkpoint from a different adapter class or version.

Common situations: Adapter checkpoint from a different adapter architecture than the config's _class_name indicates; weight-name remapping bug in the loader for a new adapter variant; mixing checkpoints from different revisions of the same model family.

Related errors

• Model config does not contain a _class_name attribute. Only
• {component_name!r} checkpoint declares quantization metadata
• Unsupported model type: {model_type}
• Z-Image transformer has no `rotary_emb`. It likely loaded vi
• Model config does not contain a _class_name attribute. Only

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