unslothai/unsloth · error · RuntimeError

Metadata unavailable while resolving GGUF variant '{variant}

Error message

Metadata unavailable while resolving GGUF variant '{variant}' for {repo_id}

What it means

Raised by _gguf_variant_target_plan when the Hugging Face Hub metadata call (_model_info_with_retry) fails before the GGUF variant plan can be built. The worker needs the repo's sibling file list to map a variant name (e.g. Q4_K_M) onto concrete .gguf shards; without metadata it cannot proceed. The original exception is chained via 'raise ... from e', and a diagnostic is printed to stderr including the exception type and message.

Source

Thrown at studio/backend/hub/workers/hf_download.py:616

        repo_id,
        None,
        snapshot_path,
        metadata_unavailable = info is None,
    )


def _gguf_variant_target_plan(
    repo_id: str, variant: str, hf_token: str | None
) -> GgufVariantPlan | None:
    try:
        info = _model_info_with_retry(repo_id, hf_token)
    except Exception as e:
        print(
            f"metadata unavailable, cannot resolve GGUF variant '{variant}' "
            f"for {repo_id} ({type(e).__name__}: {e})",
            file = sys.stderr,
        )
        raise RuntimeError(
            f"Metadata unavailable while resolving GGUF variant '{variant}' " f"for {repo_id}"
        ) from e
    # plan_for_variant, not .get: a repo that files every variant under one shared container
    # qualifies every key, and a stored pin or an explicit repo:Q4_K_M then missed the map and
    # the worker exited with "No GGUF shards matching variant".
    return plan_for_variant(build_gguf_variant_plans(list(info.siblings)), variant)


def _download_gguf_variant(repo_id: str, variant: str, hf_token: str | None, mode: str) -> None:
    from huggingface_hub import snapshot_download
    from hub.utils.download_registry import prepare_cache_for_transport
    from hub.utils.hf_cache_state import has_active_incomplete_blobs
    from hub.utils import download_manifest

    metadata_unavailable = False
    try:
        plan = _gguf_variant_target_plan(repo_id, variant, hf_token)
    except RuntimeError:

View on GitHub (pinned to 203007d190)

Solutions

Check stderr for the '(TypeName: message)' suffix — it names the underlying cause (e.g. ConnectionError, GatedRepoError, 401) which determines the fix.
Verify network reachability of huggingface.co from the worker (curl https://huggingface.co/api/models/<repo_id>) and fix proxy/DNS/TLS config if it fails.
If the cause is auth (401/403), refresh or supply a valid hf_token with access to the (possibly gated) repo.
If it is transient (timeout/5xx), simply re-trigger the download once connectivity is restored; the retry wrapper already handles short blips.
If a TLS-inspecting proxy is the culprit, configure the backend's native TLS activation (utils.native_tls) or add the proxy CA to the trust store.

Defensive patterns

Strategy: retry

Validate before calling

import requests

def hub_reachable(repo_id: str, hf_token: str | None) -> bool:
    """Probe Hub metadata availability before starting a GGUF variant download."""
    headers = {"Authorization": f"Bearer {hf_token}"} if hf_token else {}
    try:
        r = requests.head(
            f"https://huggingface.co/api/models/{repo_id}",
            headers=headers, timeout=10,
        )
        return r.status_code < 500
    except requests.RequestException:
        return False

Try / catch

try:
    plan = _gguf_variant_target_plan(repo_id, variant, hf_token)
except RuntimeError as e:
    if "Metadata unavailable" in str(e):
        # e.__cause__ carries the underlying Hub error; retry after backoff,
        # abort permanently on auth errors (401/403)
        cause = e.__cause__
        if "401" in str(cause) or "403" in str(cause):
            raise
        time.sleep(backoff)
        continue
    raise

Prevention

Warm the HF cache or run a metadata probe before launching download workers.
Monitor stderr for the '(TypeName: message)' suffix — it distinguishes auth from network failures.
Keep hf_token current; rotated-out tokens are the most common permanent cause.
Configure proxy/TLS trust (native TLS activation) in corporate networks before scheduling downloads.

When it happens

Trigger: A GGUF download job for a repo:variant pin (e.g. 'unsloth/gemma-3-4b-it-GGUF:Q4_K_M') starts while the Hub API is unreachable: network offline, DNS failure, proxy/TLS interception rejecting the Hub cert, an invalid/revoked hf_token returning 401/403, or Hub rate limiting/downtime that exhausts the retry loop inside _model_info_with_retry.

Common situations: Air-gapped or proxied environments where huggingface.co is blocked; expired HF token after credential rotation; transient Hub 5xx outages; running the download worker on a machine where HF_HOME cache is cold so every lookup is a live network call.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/52277cbb7b0ca1ca. Report an issue: GitHub.