huggingface/transformers · error · ValueError

Fusion {fusion_name} for model type {model_type} conflicts w

Error message

Fusion {fusion_name} for model type {model_type} conflicts with an existing conversion mapping for source patterns {source_patterns}.

What it means

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.

Source

Thrown at src/transformers/fusion_mapping.py:224

        return

    register_patch_mapping(fusable_classes, overwrite=True)

    if not hasattr(cls, "config_class") or not hasattr(cls.config_class, "model_type"):
        raise ValueError(f"Model {cls.__name__} has no config class or model type")
    model_type = cls.config_class.model_type
    converters = spec.make_transforms(config)

    existing_converters = get_checkpoint_conversion_mapping(model_type)
    if existing_converters is not None:
        # WeightConverter matching stops at the first matching source pattern, so
        # conflicting converters must fail fast instead of being appended.
        existing_converter_sources = {tuple(existing.source_patterns): existing for existing in existing_converters}
        for converter in converters:
            source_patterns = tuple(converter.source_patterns)
            existing_converter = existing_converter_sources.get(source_patterns)
            if existing_converter is not None:
                raise ValueError(
                    f"Fusion {fusion_name} for model type {model_type} conflicts with an existing conversion mapping "
                    f"for source patterns {source_patterns}."
                )

        # TODO: allow compatible fusions mentioned https://github.com/huggingface/transformers/pull/45041#discussion_r3028989716
        converters = existing_converters + converters

    register_checkpoint_conversion_mapping(model_type, converters, overwrite=True)


_FUSION_REGISTRY: dict[str, ModuleFusionSpec] = {"patch_embeddings": PatchEmbeddingsFusionSpec()}


def _iter_enabled_fusions(fusion_config: Mapping[str, bool | Mapping[str, Any]]) -> list[str]:
    """Validate `fusion_config` and return enabled fusion names in user-specified order."""

    enabled_fusions = []
    for fusion_name, fusion_options in fusion_config.items():

View on GitHub (pinned to a597f97485)

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)

Example fix

# before
register_fusion_patches(cls, config, {"patch_embeddings": True})  # built-ins already registered
# after
# built-in patch_embeddings fusion is already registered for this model_type; just enable via config
config.fusion_config = {"patch_embeddings": True}

Defensive patterns

Strategy: validation

Validate before calling

from transformers.fusion_mapping import get_checkpoint_conversion_mapping

def fusion_conflicts(model_type: str, source_patterns: tuple[str, ...]) -> bool:
    existing = get_checkpoint_conversion_mapping(model_type) or []
    return any(tuple(c.source_patterns) == source_patterns for c in existing)

Try / catch

try:
    register_fusion_patches(cls, config, fusion_config)
except ValueError as e:
    if "conflicts with an existing conversion mapping" in str(e):
        logging.info("fusion already registered for %s; skipping", cls.__name__)
    else:
        raise

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/822f4fdc65e5f7f2. Report an issue: GitHub.