{"record":{"id":"dc0bb2d016fc6cfe","repo":"huggingface/transformers","slug":"all-patterns-for-a-fused-kernel-must-share-the-sam","errorCode":null,"errorMessage":"All patterns for a fused kernel must share the same parent module, got {glob_patterns}","messagePattern":"All patterns for a fused kernel must share the same parent module, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/hub_kernels.py","lineNumber":957,"sourceCode":"\n            # Keep the original repo string so kernelize can replace the layout's forward.\n            new_mapping[kernel_cls.__name__] = final_repo\n\n        # Case 2: fusion.\n        elif isinstance(layer_name, tuple):\n            if layout_cls is None:\n                raise ValueError(\n                    f\"Fused kernel {kernel_cls.__name__!r} requires a companion layout class \"\n                    f\"named '{kernel_cls.__name__}Layout' in the same module.\"\n                )\n\n            layout_cls.kernel_layer_name = kernel_cls.__name__\n\n            glob_patterns = [item[1] for item in layer_name]\n            parent_patterns = [p.rsplit(\".\", 1)[0] for p in glob_patterns]\n\n            if len(set(parent_patterns)) != 1:\n                raise ValueError(\n                    f\"All patterns for a fused kernel must share the same parent module, got {glob_patterns}\"\n                )\n\n            parent_pattern = parent_patterns[0].replace(\"*\", r\"\\w+\")\n            child_names = [p.rsplit(\".\", 1)[1] for p in glob_patterns]\n\n            if meta_model is None:\n                with torch.device(\"meta\"):\n                    meta_model = cls(config)\n\n            matched_any = False\n            for name, module in meta_model.named_modules():\n                if not re.fullmatch(parent_pattern, name):\n                    continue\n                if not all(hasattr(module, child) for child in child_names):\n                    raise ValueError(\n                        f\"Module {name!r} does not have the expected child modules {child_names} required for \"\n                        f\"the fused kernel {kernel_cls.__name__!r}\"","sourceCodeStart":939,"sourceCodeEnd":975,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/hub_kernels.py#L939-L975","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Restrict the fusion entry's patterns to children of one parent module (all must share the same dotted prefix before the last component).","If you truly need cross-parent fusion, that is unsupported — split into per-parent kernels or restructure the kernel to patch a single parent.","Double-check for typos in the shared prefix (e.g. singular/plural layer names, wrong wildcard placement)."],"exampleFix":"// before\n[[0, \"model.layers.*.mlp.gate_proj\"], [1, \"model.layers.*.self_attn.q_proj\"]]\n\n// after\n[[0, \"model.layers.*.mlp.gate_proj\"], [1, \"model.layers.*.mlp.up_proj\"], [2, \"model.layers.*.mlp.down_proj\"]]","handlingStrategy":"validation","validationCode":"def validate_fusion_patterns(patterns: list[str]) -> bool:\n    parents = {p.rsplit('.', 1)[0] for p in patterns}\n    return len(parents) == 1 and all('.' in p for p in patterns)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive fusion entries mechanically: pick one parent module path and list only its direct children.","Add a unit test over your kernel config asserting one shared parent per fusion key."],"tags":["hub-kernels","fusion","kernel-config"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}