sgl-project/sglang · error · RuntimeError

gguf package does not provide the DeepSeek name map

Error message

gguf package does not provide the DeepSeek name map

What it means

build_deepseek4_checkpoint_name_map tries gguf_module.MODEL_ARCH.DEEPSEEK2 to obtain the GGUF tensor name map for DeepSeek weights, and raises RuntimeError if that attribute doesn't exist. This means the installed gguf package version doesn't ship the DeepSeek architecture mapping that the DeepSeek-V4 GGUF loader requires.

Source

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

        priority = 3
    return priority, len(alias), alias


def build_deepseek4_checkpoint_name_map(
    gguf_module: Any,
    tensor_names: Iterable[str],
    num_layers: int,
) -> dict[str, str]:
    """Map every source GGUF tensor to a DeepSeek checkpoint tensor name.

    The function fails closed if a source tensor has no deterministic mapping
    or if two source tensors would load the same checkpoint tensor.
    """

    try:
        arch = gguf_module.MODEL_ARCH.DEEPSEEK2
    except AttributeError as exc:
        raise RuntimeError(
            "gguf package does not provide the DeepSeek name map"
        ) from exc

    name_map = gguf_module.get_tensor_name_map(arch, num_layers)
    aliases_by_gguf_base: dict[str, list[str]] = defaultdict(list)
    for alias, mapping in name_map.mapping.items():
        aliases_by_gguf_base[mapping[1]].append(alias)

    result: dict[str, str] = {}
    reverse: dict[str, str] = {}
    missing: list[str] = []
    for tensor_name in tensor_names:
        checkpoint_name = _v4_checkpoint_name(tensor_name)
        if checkpoint_name is None:
            base, suffix = _split_suffix(tensor_name)
            candidates = aliases_by_gguf_base.get(base, ())
            if candidates:
                alias = min(candidates, key=_candidate_score)

View on GitHub (pinned to 0132848349)

Solutions

  1. Upgrade the gguf package: pip install -U gguf (verify gguf.MODEL_ARCH.DEEPSEEK2 exists)
  2. Check for a local file/module named gguf.py shadowing the real package; remove or rename it
  3. Recreate/repair the environment so the correct gguf distribution is imported (pip show gguf)

Example fix

# before
gguf==0.9.0  # no DEEPSEEK2 arch
# after
pip install -U "gguf>=0.10"
python -c "import gguf; gguf.MODEL_ARCH.DEEPSEEK2"
Defensive patterns

Strategy: validation

Validate before calling

import gguf
if not hasattr(gguf.MODEL_ARCH, 'DEEPSEEK2'):
    raise RuntimeError('installed gguf lacks DEEPSEEK2 support; run: pip install -U gguf')

Try / catch

try:
    it = deepseek4_nonexpert_weights_iterator(path, num_layers)
except RuntimeError as e:
    if 'does not provide the DeepSeek name map' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-U', 'gguf'])
        raise  # restart process to reload module
    raise

Prevention

When it happens

Trigger: Calling deepseek4_nonexpert_weights_iterator (DeepSeek GGUF loading) with an installed gguf package that predates DeepSeek2 support, i.e. gguf.MODEL_ARCH has no DEEPSEEK2 member.

Common situations: Old gguf pip package (<0.10-ish), a different package shadowing the name gguf, or a downgraded environment after a dependency resolution conflict.

Related errors

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