huggingface/transformers · error · ValueError

All patterns for a fused kernel must share the same parent m

Error message

All patterns for a fused kernel must share the same parent module, got {glob_patterns}

What it means

For a fused kernel, every child pattern in the tuple key must live under the same parent module, because the fusion patches a single parent class whose __init__ replaces the listed children with the kernel plus nn.Identity()s. The code takes each 'parent.child' pattern's parent prefix and requires exactly one distinct parent; otherwise this ValueError is raised.

Source

Thrown at src/transformers/integrations/hub_kernels.py:957

            # Keep the original repo string so kernelize can replace the layout's forward.
            new_mapping[kernel_cls.__name__] = final_repo

        # Case 2: fusion.
        elif isinstance(layer_name, tuple):
            if layout_cls is None:
                raise ValueError(
                    f"Fused kernel {kernel_cls.__name__!r} requires a companion layout class "
                    f"named '{kernel_cls.__name__}Layout' in the same module."
                )

            layout_cls.kernel_layer_name = kernel_cls.__name__

            glob_patterns = [item[1] for item in layer_name]
            parent_patterns = [p.rsplit(".", 1)[0] for p in glob_patterns]

            if len(set(parent_patterns)) != 1:
                raise ValueError(
                    f"All patterns for a fused kernel must share the same parent module, got {glob_patterns}"
                )

            parent_pattern = parent_patterns[0].replace("*", r"\w+")
            child_names = [p.rsplit(".", 1)[1] for p in glob_patterns]

            if meta_model is None:
                with torch.device("meta"):
                    meta_model = cls(config)

            matched_any = False
            for name, module in meta_model.named_modules():
                if not re.fullmatch(parent_pattern, name):
                    continue
                if not all(hasattr(module, child) for child in child_names):
                    raise ValueError(
                        f"Module {name!r} does not have the expected child modules {child_names} required for "
                        f"the fused kernel {kernel_cls.__name__!r}"

View on GitHub (pinned to a597f97485)

Solutions

1. Restrict the fusion entry's patterns to children of one parent module (all must share the same dotted prefix before the last component).
2. If you truly need cross-parent fusion, that is unsupported — split into per-parent kernels or restructure the kernel to patch a single parent.
3. Double-check for typos in the shared prefix (e.g. singular/plural layer names, wrong wildcard placement).

Example fix

// before
[[0, "model.layers.*.mlp.gate_proj"], [1, "model.layers.*.self_attn.q_proj"]]

// after
[[0, "model.layers.*.mlp.gate_proj"], [1, "model.layers.*.mlp.up_proj"], [2, "model.layers.*.mlp.down_proj"]]

def validate_fusion_patterns(patterns: list[str]) -> bool:
    parents = {p.rsplit('.', 1)[0] for p in patterns}
    return len(parents) == 1 and all('.' in p for p in patterns)

When it happens

Trigger: A fusion key mixing patterns from different parents, e.g. [(0, 'model.layers.*.mlp.gate_proj'), (1, 'model.layers.*.self_attn.q_proj')] — 'model.layers.*.mlp' vs 'model.layers.*.self_attn' differ, so set(parent_patterns) has size 2.

Common situations: Hand-authoring a fusion mapping to combine attention and MLP ops into one kernel; renaming model components so previously aligned prefixes diverge; copy-pasting patterns between entries.

Related errors

• Invalid hub repo {hub_repo!r} for layer {layer_name!r}
• Invalid kernel repo string {repo_str!r} for layer {layer_nam
• Fused kernel {kernel_cls.__name__!r} requires a companion la
• Module {name!r} does not have the expected child modules {ch
• No module matched pattern {parent_pattern!r} for fused kerne

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