{"record":{"id":"15ca4664137c08ef","repo":"huggingface/transformers","slug":"could-not-load-kernel-class-from-hub-repo-hub-rep","errorCode":null,"errorMessage":"Could not load kernel class from hub_repo={hub_repo!r}","messagePattern":"Could not load kernel class from hub_repo=(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/hub_kernels.py","lineNumber":916,"sourceCode":"        if not repo_id or not layer_name_in_repo:\n            raise ValueError(f\"Invalid kernel repo string {repo_str!r} for layer {layer_name!r}\")\n\n        if kernel_config.use_local_kernel:\n            repo = LocalLayerRepository(\n                repo_path=Path(repo_id),\n                layer_name=layer_name_in_repo,\n            )\n        else:\n            repo = LayerRepository(\n                repo_id=repo_id,\n                layer_name=layer_name_in_repo,\n                **metadata,\n            )\n\n        kernel_cls = repo.load()\n\n        if kernel_cls is None:\n            raise ValueError(f\"Could not load kernel class from hub_repo={hub_repo!r}\")\n\n        kernel_mod = sys.modules.get(kernel_cls.__module__)\n        layout_cls = getattr(kernel_mod, f\"{kernel_cls.__name__}Layout\", None) if kernel_mod else None\n\n        if layout_cls is not None and \"forward\" not in layout_cls.__dict__:\n\n            @functools.wraps(kernel_cls.forward)\n            def _noop_forward(self, *args, **kwargs):\n                pass\n\n            layout_cls.forward = _noop_forward\n\n        # Case 1: no fusion.\n        if isinstance(layer_name, str):\n            # No layout class: stateless kernel, leave for kernels.kernelize.\n            if layout_cls is None:\n                new_mapping[layer_name] = final_repo\n                continue","sourceCodeStart":898,"sourceCodeEnd":934,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/hub_kernels.py#L898-L934","documentation":"register_kernel_replacements_and_fusions calls repo.load() (LayerRepository or LocalLayerRepository) to fetch and import the kernel class from the hub or local path. If load() returns None — the repository has no matching layer, the download/import silently failed, or trust_remote_code gating resolved to a no-op — this ValueError is raised. It means the configured kernel repo exists as a string but yielded no loadable class.","triggerScenarios":"Loading a model with a kernels=... config whose repo:layer pair points to a layer that does not exist in the hub repo (LayerRepository.load returns None); a local kernel path missing the expected module/class; trust_remote_code=False for a kernel requiring remote code without ALLOW_ALL_KERNELS set.","commonSituations":"Kernel repo renamed or the layer name inside it changed; offline/Hub network failures surfacing as None; version pinning (revision=) pointing at an old revision without that layer; local kernel directory layout not matching what LocalLayerRepository expects.","solutions":["Verify the layer name segment of 'repo:layer' matches the layer actually exported by the hub repo (check the repo page for its kernel layer names).","Set trust_remote_code=True in the kernel metadata (or the appropriate kernels trust flag) if the kernel requires it.","For local kernels, confirm the directory contains the expected layer file/class named after layer_name_in_repo.","Check hub connectivity / try downloading the repo manually (huggingface-cli download <repo_id>) to rule out network issues; if the repo moved, update the mapping to the new repo id."],"exampleFix":"// before\n{\"layer\": [\"kernels-community/old-repo:old_layer\", {\"version\": 1}]}\n\n// after\n{\"layer\": [\"kernels-community/new-repo:the_layer\", {\"version\": 1, \"trust_remote_code\": true}]}","handlingStrategy":"validation","validationCode":"from huggingface_hub import HfApi\n\ndef kernel_repo_has_layer(repo_id: str, layer_name: str) -> bool:\n    try:\n        files = [f.rfilename for f in HfApi().repo_info(repo_id, files_metadata=False).siblings]\n        return any(layer_name in f for f in files)\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    kernel_cls = repo.load()\nexcept ValueError as e:\n    if \"Could not load kernel class\" in str(e):\n        raise ConfigError(f\"kernel repo {hub_repo!r} unusable: check layer name and trust_remote_code\") from e\n    raise","preventionTips":["Pass trust_remote_code=True for third-party kernels or set the library's allow-all-kernels flag consciously.","Pin a known-good revision of the kernel repo so renames cannot break loads.","Smoke-test custom kernel repos by loading them standalone before wiring into model configs."],"tags":["hub-kernels","loading","network"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}