huggingface/transformers · error · ValueError

Unknown fusion type: {fusion_name}

Error message

Unknown fusion type: {fusion_name}

What it means

The fusion config validator only accepts keys present in _FUSION_REGISTRY (currently 'patch_embeddings'). Any other key means the fusion name is unknown to this transformers version, so it rejects it instead of silently ignoring a requested fusion.

Source

Thrown at src/transformers/fusion_mapping.py:244

                    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():
        if fusion_name not in _FUSION_REGISTRY:
            raise ValueError(f"Unknown fusion type: {fusion_name}")
        if fusion_options is False:
            continue
        if fusion_options is not True and not isinstance(fusion_options, Mapping):
            raise ValueError(
                f"Invalid fusion config for {fusion_name}: expected `True`, `False`, or a mapping of options."
            )
        enabled_fusions.append(fusion_name)
    return enabled_fusions


def register_fusion_patches(
    cls: "type[PreTrainedModel]", config, fusion_config: Mapping[str, bool | Mapping[str, Any]] | None = None
) -> None:
    """Register requested runtime fusions for `cls`.

    This function:
    - validates `fusion_config` against `_FUSION_REGISTRY`
    - resolves the enabled fusion families in user order

View on GitHub (pinned to a597f97485)

Solutions

1. Use only registered fusion names; check transformers.models.fusion_mapping._FUSION_REGISTRY for what your version supports
2. Upgrade/downgrade transformers to the version whose fusion set matches your config
3. Fix typos in fusion names inside the config

Example fix

# before
config.fusion_config = {"patch_embedding": True}  # typo
# after
config.fusion_config = {"patch_embeddings": True}

from transformers.fusion_mapping import _FUSION_REGISTRY

def sanitize_fusion_config(cfg: dict) -> dict:
    unknown = set(cfg) - set(_FUSION_REGISTRY)
    if unknown:
        raise ValueError(f"Unknown fusion types: {unknown}; supported: {sorted(_FUSION_REGISTRY)}")
    return cfg

def is_known_fusion(name: str) -> bool:
    from transformers.fusion_mapping import _FUSION_REGISTRY
    return name in _FUSION_REGISTRY

When it happens

Trigger: Passing config.fusion_config = {'mha_fusion': True} or any name not in the registry when loading/creating a model with register_fusion_patches.

Common situations: Fusion names from a different transformers version (newer fusions on an older install, or renamed fusions), or hand-written fusion_config dicts guessing at names.

Related errors

• Invalid fusion config for {fusion_name}: expected `True`, `F
• Model {cls.__name__} has no config class or model type
• Fusion {fusion_name} for model type {model_type} conflicts w
• Can't load feature extractor for '{pretrained_model_name_or_
• Can't load feature extractor for '{pretrained_model_name_or_

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