{"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":"http","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/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/huggingface/common_utils.py#L80-L103","documentation":"Raised in _fetch_inference_provider_mapping when the outbound HTTP request to the HF Hub API (https://huggingface.co/api/models/<model>?expand=inferenceProviderMapping) fails at the transport/HTTP layer (httpx.HTTPError). The handler maps any attached response status (401/403/429/5xx) or defaults to 500 and re-raises as HuggingFaceError with the underlying exception text.","triggerScenarios":"Network-level failure reaching huggingface.co (DNS, TLS, firewall, air-gapped environment); Hub returns 429 rate-limit or 5xx outage; proxy interference; HTTP 401/403 when an invalid token is set such that the Hub API rejects the request. Only httpx.HTTPError subclasses hit this branch — response.raise_for_status() failures (4xx/5xx) and connection errors both land here.","commonSituations":"Corporate network with blocked or MITM-proxied egress to huggingface.co; intermittent Hub outages or rate limiting from many lookups (each hf chat call without api_base triggers a Hub lookup); misconfigured HTTPS_PROXY; air-gapped deployment where HF calls were never intended but api_base was not set, forcing the Hub lookup path.","solutions":["Set HF credentials/API or pass api_base: providing api_base (Inference Endpoint) skips the Hub lookup entirely — best fix for offline/locked-down environments.","Inspect the status_code in the HuggingFaceError: 429 → back off / cache provider mappings; 5xx → transient Hub issue, retry; connection errors → fix network/proxy/DNS to huggingface.co.","If you call the same model repeatedly, cache the provider mapping (or pin the resolved endpoint) instead of triggering a Hub API hit every request.","Check HTTP(S)_PROXY env vars and corporate firewall rules for *.huggingface.co."],"exampleFix":"# before — every call hits the Hub API, which can fail/rate-limit\nlitellm.completion(model='hf/meta-llama/Llama-3.1-8B-Instruct', messages=msgs)\n# HuggingFaceError: Failed to fetch provider mapping: <httpx error>\n\n# after — bypass the Hub lookup with an explicit endpoint\nlitellm.completion(\n    model='hf/meta-llama/Llama-3.1-8B-Instruct',\n    messages=msgs,\n    api_base='https://my-endpoint.endpoints.huggingface.cloud/v1',\n    api_key=os.environ['HF_TOKEN'],\n)\n","handlingStrategy":"retry","validationCode":"null  # network-side; preflight connectivity instead\n\nimport httpx\n\ndef can_reach_hf_hub() -> bool:\n    try:\n        httpx.get(\"https://huggingface.co/api/models?limit=1\", timeout=5)\n        return True\n    except httpx.HTTPError:\n        return False","typeGuard":null,"tryCatchPattern":"import time\n\nfor attempt in range(3):\n    try:\n        resp = litellm.completion(model=\"hf/org/model\", messages=msgs)\n        break\n    except Exception as e:  # HuggingFaceError wrapping httpx.HTTPError\n        msg = str(e)\n        if \"Failed to fetch provider mapping\" in msg and attempt < 2:\n            time.sleep(2 ** attempt)\n            continue\n        raise","preventionTips":["Pass api_base (HF Inference Endpoint) in locked-down/offline environments to skip the Hub lookup entirely.","Cache provider mappings per model instead of triggering a Hub API call on every request.","Monitor for HTTP 429/5xx from huggingface.co and back off; verify proxy/firewall egress for *.huggingface.co."],"tags":["huggingface","network","rate-limit","hub-api","proxy","httpx"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}