sgl-project/sglang · error · ValueError

GGUF tensors collide after parameter mapping at {alias!r}

Error message

GGUF tensors collide after parameter mapping at {alias!r}

What it means

While remapping GGUF tensor names to model parameter names, two different GGUF tensors mapped to the same target alias with different metadata (dtype/layout/shape). The loader refuses to silently overwrite one tensor's loading plan with another's.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/gguf_weights.py:184

        if metadata.is_quantized and checkpoint_name.startswith(dequantize_prefixes):
            metadata = replace(
                metadata,
                stored_shape=metadata.logical_shape,
                stored_dtype=torch.bfloat16,
                param_name=checkpoint_name,
                dequantize_on_load=True,
            )
        parameter_name = name_mapper(checkpoint_name)
        mapped_param_name = (
            f"{parameter_name.removesuffix('.weight')}.qweight"
            if metadata.is_packed
            else parameter_name
        )
        mapped_metadata = replace(metadata, param_name=mapped_param_name)
        for alias in (checkpoint_name, parameter_name):
            previous = remapped.get(alias)
            if previous is not None and previous != mapped_metadata:
                raise ValueError(
                    f"GGUF tensors collide after parameter mapping at {alias!r}"
                )
            remapped[alias] = mapped_metadata
    return remapped


def _tensor_to_torch(tensor, metadata: GGUFTensorMeta) -> torch.Tensor:
    if metadata.dequantize_on_load:
        gguf = _gguf_module()
        value = gguf.dequantize(tensor.data, metadata.weight_type)
        return torch.from_numpy(value.reshape(metadata.logical_shape)).to(
            metadata.stored_dtype
        )
    with warnings.catch_warnings():
        warnings.filterwarnings(
            "ignore",
            message="The given NumPy array is not writable",
            category=UserWarning,

View on GitHub (pinned to 0132848349)

Solutions

1. Fix the parameter mapping so each GGUF tensor maps to a unique parameter alias
2. If the collision is intentional (two names for the same tensor), make sure their metadata matches exactly — otherwise keep only one source tensor per alias
3. Print the colliding alias and both metadata records (name, shape, dtype, quant type) to identify which mapping entry is wrong

Example fix

# before: {'q.weight': 'attn.qkv.weight', 'qkv.weight': 'attn.qkv.weight'} -> collision
# after: {'qkv.weight': 'attn.qkv.weight'}  # single source of truth

def mapping_is_injective(mapping: dict[str, str]) -> bool:
    seen = {}
    for src, dst in mapping.items():
        if dst in seen and seen[dst] != src:
            return False
        seen[dst] = src
    return True

try:
    remapped = remap_gguf_tensor_meta(meta_map, mapping)
except ValueError as e:
    if 'collide after parameter mapping' in str(e):
        # inspect duplicate destinations and fix the mapping
        destinations = [v for v in mapping.values()]
        dupes = {d for d in destinations if destinations.count(d) > 1}
        raise MappingError(f'duplicate targets: {dupes}') from e
    raise

When it happens

Trigger: Calling remap_gguf_tensor_meta with a parameter mapping where two distinct checkpoint tensor names (or a checkpoint name and a parameter name) collide on one alias but carry different metadata — e.g. a mapping that maps both 'blocks.0.attn.q.weight' and 'blocks.0.attn.qkv.weight' to the same parameter. Identical metadata for both is allowed; differing metadata is not.

Common situations: Custom reverse parameter mappings for ComfyUI/MiniMax-style checkpoints that fuse or alias attention projections incorrectly; mappings authored for one checkpoint layout applied to a differently-structured GGUF; duplicated fuse rules in the mapping table.

Related errors

• Parameter {param_name} not found in the model.
• A GGUF encoder checkpoint cannot be combined with a second q
• GGUF tensor {tensor.name} declares original shape {logical_s
• Resolved GGUF path is not a GGUF file: {resolved}
• DeepSeek-V4 GGUF mapping collision: {other!r} and {tensor_na

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