huggingface/transformers · error · ValueError

Could not load kernel class from hub_repo={hub_repo!r}

Error message

Could not load kernel class from hub_repo={hub_repo!r}

What it means

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.

Source

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

        if not repo_id or not layer_name_in_repo:
            raise ValueError(f"Invalid kernel repo string {repo_str!r} for layer {layer_name!r}")

        if kernel_config.use_local_kernel:
            repo = LocalLayerRepository(
                repo_path=Path(repo_id),
                layer_name=layer_name_in_repo,
            )
        else:
            repo = LayerRepository(
                repo_id=repo_id,
                layer_name=layer_name_in_repo,
                **metadata,
            )

        kernel_cls = repo.load()

        if kernel_cls is None:
            raise ValueError(f"Could not load kernel class from hub_repo={hub_repo!r}")

        kernel_mod = sys.modules.get(kernel_cls.__module__)
        layout_cls = getattr(kernel_mod, f"{kernel_cls.__name__}Layout", None) if kernel_mod else None

        if layout_cls is not None and "forward" not in layout_cls.__dict__:

            @functools.wraps(kernel_cls.forward)
            def _noop_forward(self, *args, **kwargs):
                pass

            layout_cls.forward = _noop_forward

        # 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

View on GitHub (pinned to a597f97485)

Solutions

1. 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).
2. Set trust_remote_code=True in the kernel metadata (or the appropriate kernels trust flag) if the kernel requires it.
3. For local kernels, confirm the directory contains the expected layer file/class named after layer_name_in_repo.
4. 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.

Example fix

// before
{"layer": ["kernels-community/old-repo:old_layer", {"version": 1}]}

// after
{"layer": ["kernels-community/new-repo:the_layer", {"version": 1, "trust_remote_code": true}]}

from huggingface_hub import HfApi

def kernel_repo_has_layer(repo_id: str, layer_name: str) -> bool:
    try:
        files = [f.rfilename for f in HfApi().repo_info(repo_id, files_metadata=False).siblings]
        return any(layer_name in f for f in files)
    except Exception:
        return False

try:
    kernel_cls = repo.load()
except ValueError as e:
    if "Could not load kernel class" in str(e):
        raise ConfigError(f"kernel repo {hub_repo!r} unusable: check layer name and trust_remote_code") from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Can't load the configuration of '{}'. If you were trying to
• No baseline with name '{name}' in {RESULTS_DIR}
• The server running on {url} returned status code {output.sta
• No server currently running on {url}. To run a local server,
• Can't load the configuration of '{pretrained_model_name_or_p

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