huggingface/transformers · error · ValueError

Invalid hub repo {hub_repo!r} for layer {layer_name!r}

Error message

Invalid hub repo {hub_repo!r} for layer {layer_name!r}

What it means

Thrown by register_kernel_replacements_and_fusions while walking a KernelConfig's kernel_mapping: each value must be a string, a (repo_str, metadata) tuple, or a dict wrapping one of those. If the value is any other type after the str/tuple-to-dict normalization (so it failed the isinstance(dict) branch), this ValueError fires. It is a user-configuration validation error raised before any hub download is attempted.

Source

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

    patch_mapping: dict[str, type] = {}
    new_mapping: dict = {}

    # We might need to instantiate the model on meta device.
    # We do it lazily, only if we encounter a fused kernel.
    meta_model = None

    for layer_name, hub_repo in kernel_config.kernel_mapping.items():
        if isinstance(hub_repo, (str, tuple)):
            hub_repo = {None: hub_repo}

        if isinstance(hub_repo, dict):
            if len(hub_repo.values()) != 1:
                raise ValueError(
                    f"Expected exactly one kernel repo regardless of device/mode specificity, got {hub_repo}"
                )
        else:
            raise ValueError(f"Invalid hub repo {hub_repo!r} for layer {layer_name!r}")

        hub_repo = next(iter(hub_repo.values()))

        # Infer metadata (revision/version/trust_remote_code)
        if isinstance(hub_repo, tuple):
            repo_str, metadata = hub_repo

            revision = metadata.get("revision", None)
            version = metadata.get("version", None)
            trust_remote_code = metadata.get("trust_remote_code", False) or ALLOW_ALL_KERNELS
            metadata = {"version": version} if version is not None else {"revision": revision}
            metadata |= {"trust_remote_code": trust_remote_code}

            final_repo = (repo_str, metadata)
        else:
            repo_str = hub_repo
            metadata = {"version": 1, "trust_remote_code": ALLOW_ALL_KERNELS}
            final_repo = (repo_str, metadata)

View on GitHub (pinned to a597f97485)

Solutions

1. Fix the kernel_mapping entry for the named layer to a single 'repo_id:layer_name' string (or a one-element dict / [repo, metadata] tuple).
2. Remove stale or duplicated device/mode-specific variants from that entry's dict so exactly one repo remains.
3. Regenerate or re-download the kernel config from its hub repo instead of hand-editing, then verify with json.load that each value is a str, [str, dict], or 1-entry object.

Example fix

// before (kernel.json)
{"model.layers.*.self_attn.q_proj": ["a:b", "c:d"]}

// after
{"model.layers.*.self_attn.q_proj": "a:b"}

def validate_kernel_mapping(mapping):
    for layer, repo in mapping.items():
        if isinstance(repo, (str, tuple)):
            repo = {None: repo}
        if not isinstance(repo, dict) or len(repo.values()) != 1:
            raise ValueError(f"bad kernel_mapping entry for {layer!r}: {repo!r}")
    return True

def is_valid_hub_repo(repo) -> bool:
    if isinstance(repo, (str, tuple)):
        return True
    return isinstance(repo, dict) and len(repo.values()) == 1 and all(
        isinstance(v, (str, tuple)) for v in repo.values()
    )

try:
    register_kernel_replacements_and_fusions(model_cls, config, kernel_config)
except ValueError as e:
    if "Invalid hub repo" in str(e):
        fix_and_revalidate(kernel_config)  # repair mapping before retry
    else:
        raise

When it happens

Trigger: Calling model loading with a kernel config whose JSON kernel_mapping contains a value that is neither a string ('repo_id:layer_name'), a [repo, {metadata}] pair, nor an object with exactly one such entry — e.g. a number, boolean, null, list of strings, or a dict holding 2+ device-specific entries would first hit the sibling 'exactly one kernel repo' error; a plain list or None hits this one.

Common situations: Hand-editing a kernel JSON config and using a list of repos ['a:k', 'b:k'] instead of a single string; passing YAML null for a layer; schema drift between the kernel-catalog format the user copied from docs and the one this transformers version expects.

Related errors

• Invalid kernel repo string {repo_str!r} for layer {layer_nam
• All patterns for a fused kernel must share the same parent m
• PUSH_TO_HUB_TOKEN is not set, cannot push results to the Hub
• reference must be greater than zero
• min_value must be greater than zero

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