{"record":{"id":"822f4fdc65e5f7f2","repo":"huggingface/transformers","slug":"fusion-fusion-name-for-model-type-model-type-c","errorCode":null,"errorMessage":"Fusion {fusion_name} for model type {model_type} conflicts with an existing conversion mapping for source patterns {source_patterns}.","messagePattern":"Fusion (.+?) for model type (.+?) conflicts with an existing conversion mapping for source patterns (.+?)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/fusion_mapping.py","lineNumber":224,"sourceCode":"        return\n\n    register_patch_mapping(fusable_classes, overwrite=True)\n\n    if not hasattr(cls, \"config_class\") or not hasattr(cls.config_class, \"model_type\"):\n        raise ValueError(f\"Model {cls.__name__} has no config class or model type\")\n    model_type = cls.config_class.model_type\n    converters = spec.make_transforms(config)\n\n    existing_converters = get_checkpoint_conversion_mapping(model_type)\n    if existing_converters is not None:\n        # WeightConverter matching stops at the first matching source pattern, so\n        # conflicting converters must fail fast instead of being appended.\n        existing_converter_sources = {tuple(existing.source_patterns): existing for existing in existing_converters}\n        for converter in converters:\n            source_patterns = tuple(converter.source_patterns)\n            existing_converter = existing_converter_sources.get(source_patterns)\n            if existing_converter is not None:\n                raise ValueError(\n                    f\"Fusion {fusion_name} for model type {model_type} conflicts with an existing conversion mapping \"\n                    f\"for source patterns {source_patterns}.\"\n                )\n\n        # TODO: allow compatible fusions mentioned https://github.com/huggingface/transformers/pull/45041#discussion_r3028989716\n        converters = existing_converters + converters\n\n    register_checkpoint_conversion_mapping(model_type, converters, overwrite=True)\n\n\n_FUSION_REGISTRY: dict[str, ModuleFusionSpec] = {\"patch_embeddings\": PatchEmbeddingsFusionSpec()}\n\n\ndef _iter_enabled_fusions(fusion_config: Mapping[str, bool | Mapping[str, Any]]) -> list[str]:\n    \"\"\"Validate `fusion_config` and return enabled fusion names in user-specified order.\"\"\"\n\n    enabled_fusions = []\n    for fusion_name, fusion_options in fusion_config.items():","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/fusion_mapping.py#L206-L242","documentation":"WeightConverter matching stops at the first matching source pattern, so when a fusion spec tries to register converters whose source_patterns already exist in the checkpoint conversion mapping for that model_type, the code fails fast instead of silently appending a conflicting converter. This protects checkpoint loading from ambiguous weight remapping.","triggerScenarios":"Enabling a fusion (e.g. 'patch_embeddings') on a model_type that already has converters registered with identical source_patterns — typically enabling the same fusion twice, or combining two fusion specs/spec versions that remap the same source tensors.","commonSituations":"Registering fusion patches for the same model type in two places (library defaults plus user code), or upgrading transformers where a new built-in converter overlaps a previously registered custom one.","solutions":["Remove the duplicate registration: rely on the built-in fusion converters instead of re-registering yours","Change your custom WeightConverter source_patterns so they do not collide with the existing mapping","If overriding is intentional, unregister/overwrite the mapping before calling register_fusion_patches (advanced; note the TODO about compatible fusions)"],"exampleFix":"# before\nregister_fusion_patches(cls, config, {\"patch_embeddings\": True})  # built-ins already registered\n# after\n# built-in patch_embeddings fusion is already registered for this model_type; just enable via config\nconfig.fusion_config = {\"patch_embeddings\": True}","handlingStrategy":"validation","validationCode":"from transformers.fusion_mapping import get_checkpoint_conversion_mapping\n\ndef fusion_conflicts(model_type: str, source_patterns: tuple[str, ...]) -> bool:\n    existing = get_checkpoint_conversion_mapping(model_type) or []\n    return any(tuple(c.source_patterns) == source_patterns for c in existing)","typeGuard":null,"tryCatchPattern":"try:\n    register_fusion_patches(cls, config, fusion_config)\nexcept ValueError as e:\n    if \"conflicts with an existing conversion mapping\" in str(e):\n        logging.info(\"fusion already registered for %s; skipping\", cls.__name__)\n    else:\n        raise","preventionTips":["Register fusion patches for a model type exactly once per process","Prefer built-in fusion config knobs over manual registration","Log the existing mapping when this fires to identify the duplicate source"],"tags":["python","transformers","fusion","weight-conversion","conflict"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}