{"record":{"id":"3218d1d5f935c2f4","repo":"huggingface/transformers","slug":"unknown-fusion-type-fusion-name","errorCode":null,"errorMessage":"Unknown fusion type: {fusion_name}","messagePattern":"Unknown fusion type: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/fusion_mapping.py","lineNumber":244,"sourceCode":"                    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():\n        if fusion_name not in _FUSION_REGISTRY:\n            raise ValueError(f\"Unknown fusion type: {fusion_name}\")\n        if fusion_options is False:\n            continue\n        if fusion_options is not True and not isinstance(fusion_options, Mapping):\n            raise ValueError(\n                f\"Invalid fusion config for {fusion_name}: expected `True`, `False`, or a mapping of options.\"\n            )\n        enabled_fusions.append(fusion_name)\n    return enabled_fusions\n\n\ndef register_fusion_patches(\n    cls: \"type[PreTrainedModel]\", config, fusion_config: Mapping[str, bool | Mapping[str, Any]] | None = None\n) -> None:\n    \"\"\"Register requested runtime fusions for `cls`.\n\n    This function:\n    - validates `fusion_config` against `_FUSION_REGISTRY`\n    - resolves the enabled fusion families in user order","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/fusion_mapping.py#L226-L262","documentation":"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.","triggerScenarios":"Passing config.fusion_config = {'mha_fusion': True} or any name not in the registry when loading/creating a model with register_fusion_patches.","commonSituations":"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.","solutions":["Use only registered fusion names; check transformers.models.fusion_mapping._FUSION_REGISTRY for what your version supports","Upgrade/downgrade transformers to the version whose fusion set matches your config","Fix typos in fusion names inside the config"],"exampleFix":"# before\nconfig.fusion_config = {\"patch_embedding\": True}  # typo\n# after\nconfig.fusion_config = {\"patch_embeddings\": True}","handlingStrategy":"validation","validationCode":"from transformers.fusion_mapping import _FUSION_REGISTRY\n\ndef sanitize_fusion_config(cfg: dict) -> dict:\n    unknown = set(cfg) - set(_FUSION_REGISTRY)\n    if unknown:\n        raise ValueError(f\"Unknown fusion types: {unknown}; supported: {sorted(_FUSION_REGISTRY)}\")\n    return cfg","typeGuard":"def is_known_fusion(name: str) -> bool:\n    from transformers.fusion_mapping import _FUSION_REGISTRY\n    return name in _FUSION_REGISTRY","tryCatchPattern":null,"preventionTips":["Print _FUSION_REGISTRY keys when writing fusion configs for your installed version","Pin the transformers version your configs were authored against"],"tags":["python","transformers","fusion","config-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}