{"record":{"id":"6becea2bc4229e9c","repo":"BerriAI/litellm","slug":"failed-to-fetch-provider-mapping-e","errorCode":null,"errorMessage":"Failed to fetch provider mapping: {e}","messagePattern":"Failed to fetch provider mapping: (.+?)","errorType":"exception","errorClass":"HuggingFaceError","httpStatus":null,"severity":"error","filePath":"litellm/llms/huggingface/common_utils.py","lineNumber":98,"sourceCode":"    params: Final = {\"expand\": [\"inferenceProviderMapping\"]}\n\n    try:\n        response: Final = httpx.get(path, headers=headers, params=params)\n        response.raise_for_status()\n        provider_mapping: Final = response.json().get(\"inferenceProviderMapping\")\n\n        if provider_mapping is None:\n            raise ValueError(f\"No provider mapping found for model {model}\")\n\n        return provider_mapping\n    except httpx.HTTPError as e:\n        if hasattr(e, \"response\"):\n            status_code = getattr(e.response, \"status_code\", 500)\n            headers = getattr(e.response, \"headers\", {})\n        else:\n            status_code = 500\n            headers = {}\n        raise HuggingFaceError(\n            message=f\"Failed to fetch provider mapping: {e}\",\n            status_code=status_code,\n            headers=headers,\n        )\n","sourceCodeStart":80,"sourceCodeEnd":103,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/llms/huggingface/common_utils.py#L80-L103","documentation":"While fetching the provider mapping from the HF Hub API, any httpx.HTTPError (connection failure, DNS error, or a non-2xx status via raise_for_status) is converted into HuggingFaceError with message 'Failed to fetch provider mapping: <e>' and the upstream status code (500 when there is no response object). This is a transport/upstream failure talking to huggingface.co, not a verdict on your model.","triggerScenarios":"Network egress blocked from the runtime; DNS failure; Hub returning 401/403 (bad token), 404 (repo does not exist), 429 (rate limited), or 5xx. The lookup happens lazily on the first 'hf/<provider>/<model>' call without api_base, and is lru_cached afterwards.","commonSituations":"Corporate proxies/firewalls blocking huggingface.co; air-gapped or offline environments; an invalid HUGGINGFACE_API_KEY causing 401 on every call; Hub outages; CI runners with restricted networking.","solutions":["Check the embedded status code: 401/403 → fix HUGGINGFACE_API_KEY; 404 → wrong model id; 429/5xx → back off and retry later","Verify basic connectivity from the same host: curl 'https://huggingface.co/api/models/<model>?expand=inferenceProviderMapping'","Configure proxy env vars (HTTPS_PROXY) if egress goes through a proxy","If the environment cannot reach the Hub at all, bypass routing by passing api_base to a self-hosted endpoint","Retry transient failures — the mapping fetch is not retried internally"],"exampleFix":"# before\nlitellm.completion(model=\"hf/hf-inference/meta-llama/Llama-3.1-8B-Instruct\", messages=msgs)  # no network to hf.co\n\n# after — self-hosted endpoint, no Hub lookup needed\nlitellm.completion(\n    model=\"hf/meta-llama/Llama-3.1-8B-Instruct\",\n    api_base=\"https://xxxx.endpoints.huggingface.cloud/v1\",\n    api_key=os.environ[\"HUGGINGFACE_API_KEY\"],\n    messages=msgs,\n)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"Catch HuggingFaceError around the completion/embedding call and branch on status_code: 429/5xx and connection errors → retry with exponential backoff and jitter (the Hub fetch is not internally retried); 401/403 → fix the token and stop; 404 → wrong model id, do not retry. Optionally fall back to a self-hosted api_base when the Hub is unreachable.","preventionTips":["Cache provider mappings in your own layer with a TTL instead of relying on every cold process hitting the Hub","Run from networks with verified egress to huggingface.co, or pre-configure api_base in locked-down environments","Set a valid HUGGINGFACE_API_KEY and monitor for 401s that indicate token expiry"],"tags":["huggingface","network","http-error","inference-providers","litellm"],"backgroundTag":"upstream-api-request-failed","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}