huggingface/transformers · error · ValueError

Invalid fusion config for {fusion_name}: expected `True`, `F

Error message

Invalid fusion config for {fusion_name}: expected `True`, `False`, or a mapping of options.

What it means

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.

Source

Thrown at src/transformers/fusion_mapping.py:248

        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
    - registers monkey patches and checkpoint transforms before model instantiation
    """

    if not fusion_config:

View on GitHub (pinned to a597f97485)

Solutions

1. Use booleans: {'patch_embeddings': True} or {'patch_embeddings': False}
2. Use an options dict when customizing: {'patch_embeddings': {'some_option': value}}
3. Validate loaded JSON fusion configs before passing them (bools may arrive as strings)

Example fix

# before (loaded from JSON, values are strings)
config.fusion_config = {"patch_embeddings": "true"}
# after
config.fusion_config = {"patch_embeddings": True}

from collections.abc import Mapping

def validate_fusion_config(cfg: dict) -> dict:
    for name, opts in cfg.items():
        if opts is False:
            continue
        if opts is not True and not isinstance(opts, Mapping):
            raise ValueError(f"fusion {name}: value must be True/False/mapping, got {opts!r}")
    return cfg

from collections.abc import Mapping

def is_valid_fusion_value(v) -> bool:
    return v is True or v is False or isinstance(v, Mapping)

When it happens

Trigger: config.fusion_config = {'patch_embeddings': 1} or {'patch_embeddings': 'true'} or {'patch_embeddings': None} passed to register_fusion_patches / model construction.

Common situations: Fusion config round-tripped through JSON with strings instead of booleans, or written from memory with wrong value types.

Related errors

• Unknown fusion type: {fusion_name}
• Model {cls.__name__} has no config class or model type
• Fusion {fusion_name} for model type {model_type} conflicts w
• You provided `compile_config` as an instance of {}, but it m
• only a single or a list of entries is supported but got type

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