{"record":{"id":"34d88ccb1e9652e4","repo":"huggingface/transformers","slug":"invalid-fusion-config-for-fusion-name-expected","errorCode":null,"errorMessage":"Invalid fusion config for {fusion_name}: expected `True`, `False`, or a mapping of options.","messagePattern":"Invalid fusion config for (.+?): expected `True`, `False`, or a mapping of options\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/fusion_mapping.py","lineNumber":248,"sourceCode":"        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\n    - registers monkey patches and checkpoint transforms before model instantiation\n    \"\"\"\n\n    if not fusion_config:","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/fusion_mapping.py#L230-L266","documentation":"Each fusion entry in fusion_config must be True (enable with defaults), False (disable), or a Mapping of options. Any other type (int, string, list, None) is rejected because the fusion machinery cannot interpret it.","triggerScenarios":"config.fusion_config = {'patch_embeddings': 1} or {'patch_embeddings': 'true'} or {'patch_embeddings': None} passed to register_fusion_patches / model construction.","commonSituations":"Fusion config round-tripped through JSON with strings instead of booleans, or written from memory with wrong value types.","solutions":["Use booleans: {'patch_embeddings': True} or {'patch_embeddings': False}","Use an options dict when customizing: {'patch_embeddings': {'some_option': value}}","Validate loaded JSON fusion configs before passing them (bools may arrive as strings)"],"exampleFix":"# before (loaded from JSON, values are strings)\nconfig.fusion_config = {\"patch_embeddings\": \"true\"}\n# after\nconfig.fusion_config = {\"patch_embeddings\": True}","handlingStrategy":"type-guard","validationCode":"from collections.abc import Mapping\n\ndef validate_fusion_config(cfg: dict) -> dict:\n    for name, opts in cfg.items():\n        if opts is False:\n            continue\n        if opts is not True and not isinstance(opts, Mapping):\n            raise ValueError(f\"fusion {name}: value must be True/False/mapping, got {opts!r}\")\n    return cfg","typeGuard":"from collections.abc import Mapping\n\ndef is_valid_fusion_value(v) -> bool:\n    return v is True or v is False or isinstance(v, Mapping)","tryCatchPattern":null,"preventionTips":["After loading fusion_config from JSON, coerce 'true'/'false' strings to booleans","Never use ints (0/1) as boolean substitutes in fusion configs"],"tags":["python","transformers","fusion","config-validation","type-error"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}