sgl-project/sglang · error · RuntimeError

No DeepSeek-V4 checkpoint mapping for {len(missing)} GGUF te

Error message

No DeepSeek-V4 checkpoint mapping for {len(missing)} GGUF tensors: {preview}

What it means

After mapping GGUF tensors to checkpoint names, some GGUF tensors had no checkpoint counterpart and are listed (up to 8) in this RuntimeError. The DeepSeek-V4 GGUF loader requires a complete, exhaustive mapping, so unmapped tensors — typically new/renamed tensor types in a newer GGUF conversion — abort loading.

Source

Thrown at python/sglang/srt/model_loader/deepseek4_gguf.py:177

                checkpoint_name = alias
                if suffix and not alias.endswith(f".{suffix}"):
                    checkpoint_name += f".{suffix}"

        if checkpoint_name is None:
            missing.append(tensor_name)
            continue
        if checkpoint_name in reverse:
            other = reverse[checkpoint_name]
            raise RuntimeError(
                "DeepSeek-V4 GGUF mapping collision: "
                f"{other!r} and {tensor_name!r} -> {checkpoint_name!r}"
            )
        result[tensor_name] = checkpoint_name
        reverse[checkpoint_name] = tensor_name

    if missing:
        preview = ", ".join(repr(name) for name in missing[:8])
        raise RuntimeError(
            f"No DeepSeek-V4 checkpoint mapping for {len(missing)} GGUF tensors: "
            f"{preview}"
        )
    return result

View on GitHub (pinned to 0132848349)

Solutions

Match versions: use the gguf package / llama.cpp conversion tool version compatible with this sglang release
Check the preview list of missing tensor names — if they are unused extras, convert the GGUF with flags that omit them or re-convert with the standard script
Verify num_layers passed in matches the GGUF's count.header (llama.cpp inspect) and the model config
Upgrade sglang — newer releases may add mappings for recently added GGUF tensor types

Defensive patterns

Strategy: validation

Validate before calling

import gguf
name_map = gguf.get_tensor_name_map(gguf.MODEL_ARCH.DEEPSEEK2, num_layers)
reader = gguf.GGUFReader(path)
unmapped = [t.name for t in reader.tensors if not any(
    name_map.mapping.get(a) and name_map.mapping[a].name for a in [t.name])]
if unmapped:
    print('unmapped tensors present:', unmapped[:8])

Prevention

Use gguf conversion and reader from the same llama.cpp/gguf version pair
Verify num_layers matches the GGUF header before loading
Test-load each new GGUF file once in a scratch job before deployment

When it happens

Trigger: Calling deepseek4_nonexpert_weights_iterator on a GGUF file containing tensor names (e.g. new layer types or renamed keys) that gguf.get_tensor_name_map for DEEPSEEK2 does not map for the given num_layers; the missing list is non-empty.

Common situations: GGUF converted by newer llama.cpp with extra tensors (e.g. new norm/attention keys) not in the installed gguf name map, num_layers mismatch with the file, or a gguf package version skew.

Related errors

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