huggingface/transformers · error · ValueError

Fused kernel {kernel_cls.__name__!r} requires a companion la

Error message

Fused kernel {kernel_cls.__name__!r} requires a companion layout class named '{kernel_cls.__name__}Layout' in the same module.

What it means

When a kernel_mapping key is a tuple (fusion mode: multiple child modules fused into one kernel), transformers looks for a class named '<KernelCls>Layout' in the same module as the loaded kernel class to use as the fused layer's new type. Fusion without a layout class is unsupported, so a None layout_cls raises this ValueError.

Source

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

        # Case 1: no fusion.
        if isinstance(layer_name, str):
            # No layout class: stateless kernel, leave for kernels.kernelize.
            if layout_cls is None:
                new_mapping[layer_name] = final_repo
                continue

            # Register the layout class as a monkey patch for the parent module containing the target layer.
            layout_cls.kernel_layer_name = kernel_cls.__name__
            patch_mapping[layer_name] = layout_cls

            # 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:

View on GitHub (pinned to a597f97485)

Solutions

1. Add a class named exactly f'{kernel_cls.__name__}Layout' to the same Python module the kernel class lives in.
2. If the kernel is not meant to fuse multiple modules, change the kernel_mapping key from a tuple to a single dotted string.
3. Check the kernel repo's exports (dir(module)) to confirm whether the Layout class exists under a different name and update accordingly.

Example fix

# before: kernel module defines only
class FuseMLP(nn.Module): ...

# after
class FuseMLP(nn.Module): ...
class FuseMLPLayout(nn.Module):
    conversion_mapping = ...
    def forward(self, hidden_states): ...

import sys

def has_layout_class(kernel_cls) -> bool:
    mod = sys.modules.get(kernel_cls.__module__)
    return mod is not None and hasattr(mod, f"{kernel_cls.__name__}Layout")

try:
    register_kernel_replacements_and_fusions(cls, config, kernel_config)
except ValueError as e:
    if "requires a companion layout class" in str(e):
        # kernel does not support fusion: demote entry to single-layer replacement
        convert_key_to_string(kernel_config)
    else:
        raise

When it happens

Trigger: A kernel_mapping entry whose key is a list/tuple of (index, 'parent.child') patterns (e.g. [[0, 'model.layers.*.mlp.gate_proj'], [1, 'model.layers.*.mlp.up_proj']]) while the kernel repo's module defines KernelCls but no KernelClsLayout class.

Common situations: Authoring or publishing a custom fused kernel and forgetting the companion Layout class; upgrading a kernel repo where the Layout class was renamed; copying a fusion mapping onto a kernel that only supports single-layer replacement.

Related errors

• All patterns for a fused kernel must share the same parent m
• Module {name!r} does not have the expected child modules {ch
• No module matched pattern {parent_pattern!r} for fused kerne
• Model {cls.__name__} has no config class or model type
• Fusion {fusion_name} for model type {model_type} conflicts w

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