{"record":{"id":"52277cbb7b0ca1ca","repo":"unslothai/unsloth","slug":"metadata-unavailable-while-resolving-gguf-variant","errorCode":null,"errorMessage":"Metadata unavailable while resolving GGUF variant '{variant}' for {repo_id}","messagePattern":"Metadata unavailable while resolving GGUF variant '(.+?)' for (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/hub/workers/hf_download.py","lineNumber":616,"sourceCode":"        repo_id,\n        None,\n        snapshot_path,\n        metadata_unavailable = info is None,\n    )\n\n\ndef _gguf_variant_target_plan(\n    repo_id: str, variant: str, hf_token: str | None\n) -> GgufVariantPlan | None:\n    try:\n        info = _model_info_with_retry(repo_id, hf_token)\n    except Exception as e:\n        print(\n            f\"metadata unavailable, cannot resolve GGUF variant '{variant}' \"\n            f\"for {repo_id} ({type(e).__name__}: {e})\",\n            file = sys.stderr,\n        )\n        raise RuntimeError(\n            f\"Metadata unavailable while resolving GGUF variant '{variant}' \" f\"for {repo_id}\"\n        ) from e\n    # plan_for_variant, not .get: a repo that files every variant under one shared container\n    # qualifies every key, and a stored pin or an explicit repo:Q4_K_M then missed the map and\n    # the worker exited with \"No GGUF shards matching variant\".\n    return plan_for_variant(build_gguf_variant_plans(list(info.siblings)), variant)\n\n\ndef _download_gguf_variant(repo_id: str, variant: str, hf_token: str | None, mode: str) -> None:\n    from huggingface_hub import snapshot_download\n    from hub.utils.download_registry import prepare_cache_for_transport\n    from hub.utils.hf_cache_state import has_active_incomplete_blobs\n    from hub.utils import download_manifest\n\n    metadata_unavailable = False\n    try:\n        plan = _gguf_variant_target_plan(repo_id, variant, hf_token)\n    except RuntimeError:","sourceCodeStart":598,"sourceCodeEnd":634,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/hub/workers/hf_download.py#L598-L634","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import requests\n\ndef hub_reachable(repo_id: str, hf_token: str | None) -> bool:\n    \"\"\"Probe Hub metadata availability before starting a GGUF variant download.\"\"\"\n    headers = {\"Authorization\": f\"Bearer {hf_token}\"} if hf_token else {}\n    try:\n        r = requests.head(\n            f\"https://huggingface.co/api/models/{repo_id}\",\n            headers=headers, timeout=10,\n        )\n        return r.status_code < 500\n    except requests.RequestException:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    plan = _gguf_variant_target_plan(repo_id, variant, hf_token)\nexcept RuntimeError as e:\n    if \"Metadata unavailable\" in str(e):\n        # e.__cause__ carries the underlying Hub error; retry after backoff,\n        # abort permanently on auth errors (401/403)\n        cause = e.__cause__\n        if \"401\" in str(cause) or \"403\" in str(cause):\n            raise\n        time.sleep(backoff)\n        continue\n    raise","preventionTips":["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."],"tags":["network","huggingface","gguf","download","retry"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}