BerriAI/litellm · error · HuggingFaceError

Failed to fetch provider mapping: {e}

Error message

Failed to fetch provider mapping: {e}

What it means

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.

Source

Thrown at litellm/llms/huggingface/common_utils.py:98

    params: Final = {"expand": ["inferenceProviderMapping"]}

    try:
        response: Final = httpx.get(path, headers=headers, params=params)
        response.raise_for_status()
        provider_mapping: Final = response.json().get("inferenceProviderMapping")

        if provider_mapping is None:
            raise ValueError(f"No provider mapping found for model {model}")

        return provider_mapping
    except httpx.HTTPError as e:
        if hasattr(e, "response"):
            status_code = getattr(e.response, "status_code", 500)
            headers = getattr(e.response, "headers", {})
        else:
            status_code = 500
            headers = {}
        raise HuggingFaceError(
            message=f"Failed to fetch provider mapping: {e}",
            status_code=status_code,
            headers=headers,
        )

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. 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.
2. 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.
3. 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.
4. Check HTTP(S)_PROXY env vars and corporate firewall rules for *.huggingface.co.

Example fix

# before — every call hits the Hub API, which can fail/rate-limit
litellm.completion(model='hf/meta-llama/Llama-3.1-8B-Instruct', messages=msgs)
# HuggingFaceError: Failed to fetch provider mapping: <httpx error>

# after — bypass the Hub lookup with an explicit endpoint
litellm.completion(
    model='hf/meta-llama/Llama-3.1-8B-Instruct',
    messages=msgs,
    api_base='https://my-endpoint.endpoints.huggingface.cloud/v1',
    api_key=os.environ['HF_TOKEN'],
)

null  # network-side; preflight connectivity instead

import httpx

def can_reach_hf_hub() -> bool:
    try:
        httpx.get("https://huggingface.co/api/models?limit=1", timeout=5)
        return True
    except httpx.HTTPError:
        return False

import time

for attempt in range(3):
    try:
        resp = litellm.completion(model="hf/org/model", messages=msgs)
        break
    except Exception as e:  # HuggingFaceError wrapping httpx.HTTPError
        msg = str(e)
        if "Failed to fetch provider mapping" in msg and attempt < 2:
            time.sleep(2 ** attempt)
            continue
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error listing files in '{directory_path}': {e}
• Error getting file metadata for '{file_path}': {e}
• Mavvrik FOCUS destination: GCS session init missing Location
• No chat template found
• GigaChat authentication request failed: {e}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/6becea2bc4229e9c. Report an issue: GitHub.