{"record":{"id":"bd7b7f9612bc5304","repo":"sgl-project/sglang","slug":"gguf-tensors-collide-after-parameter-mapping-at-a","errorCode":null,"errorMessage":"GGUF tensors collide after parameter mapping at {alias!r}","messagePattern":"GGUF tensors collide after parameter mapping at (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/loader/gguf_weights.py","lineNumber":184,"sourceCode":"        if metadata.is_quantized and checkpoint_name.startswith(dequantize_prefixes):\n            metadata = replace(\n                metadata,\n                stored_shape=metadata.logical_shape,\n                stored_dtype=torch.bfloat16,\n                param_name=checkpoint_name,\n                dequantize_on_load=True,\n            )\n        parameter_name = name_mapper(checkpoint_name)\n        mapped_param_name = (\n            f\"{parameter_name.removesuffix('.weight')}.qweight\"\n            if metadata.is_packed\n            else parameter_name\n        )\n        mapped_metadata = replace(metadata, param_name=mapped_param_name)\n        for alias in (checkpoint_name, parameter_name):\n            previous = remapped.get(alias)\n            if previous is not None and previous != mapped_metadata:\n                raise ValueError(\n                    f\"GGUF tensors collide after parameter mapping at {alias!r}\"\n                )\n            remapped[alias] = mapped_metadata\n    return remapped\n\n\ndef _tensor_to_torch(tensor, metadata: GGUFTensorMeta) -> torch.Tensor:\n    if metadata.dequantize_on_load:\n        gguf = _gguf_module()\n        value = gguf.dequantize(tensor.data, metadata.weight_type)\n        return torch.from_numpy(value.reshape(metadata.logical_shape)).to(\n            metadata.stored_dtype\n        )\n    with warnings.catch_warnings():\n        warnings.filterwarnings(\n            \"ignore\",\n            message=\"The given NumPy array is not writable\",\n            category=UserWarning,","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/loader/gguf_weights.py#L166-L202","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the parameter mapping so each GGUF tensor maps to a unique parameter alias","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","Print the colliding alias and both metadata records (name, shape, dtype, quant type) to identify which mapping entry is wrong"],"exampleFix":"# before: {'q.weight': 'attn.qkv.weight', 'qkv.weight': 'attn.qkv.weight'} -> collision\n# after: {'qkv.weight': 'attn.qkv.weight'}  # single source of truth","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def mapping_is_injective(mapping: dict[str, str]) -> bool:\n    seen = {}\n    for src, dst in mapping.items():\n        if dst in seen and seen[dst] != src:\n            return False\n        seen[dst] = src\n    return True","tryCatchPattern":"try:\n    remapped = remap_gguf_tensor_meta(meta_map, mapping)\nexcept ValueError as e:\n    if 'collide after parameter mapping' in str(e):\n        # inspect duplicate destinations and fix the mapping\n        destinations = [v for v in mapping.values()]\n        dupes = {d for d in destinations if destinations.count(d) > 1}\n        raise MappingError(f'duplicate targets: {dupes}') from e\n    raise","preventionTips":["Unit-test mappings for injectivity before load","Version mapping tables per checkpoint family","Never fuse two checkpoint tensors onto one parameter implicitly"],"tags":["gguf","parameter-mapping","name-collision","checkpoint"],"backgroundTag":"parameter-name-mapping-collision","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}