BerriAI/litellm · critical · AuthenticationError

Cloudflare Exception - {original_exception.message}

Error message

Cloudflare Exception - {original_exception.message}

What it means

LiteLLM's Cloudflare Workers AI mapper raises AuthenticationError when the provider error string contains 'Authentication error'. Cloudflare rejected the API token: it is missing, malformed, revoked, or lacks the Workers AI permission. LiteLLM attaches the original provider response so the caller can inspect headers like WWW-Authenticate.

Source

Thrown at litellm/litellm_core_utils/exception_mapping_utils.py:1308

            raise ServiceUnavailableError(
                message=f"{custom_llm_provider.capitalize()}Exception - {error_str}",
                llm_provider=custom_llm_provider,
                model=model,
            )


def _map_cloudflare_exception(
    *,
    model: str,
    original_exception: _ProviderHTTPException,
    custom_llm_provider: str,
    error_str: str,
    exception_type: str,
    exception_provider: str,
    extra_information: str,
) -> None:
    if "Authentication error" in error_str:
        raise AuthenticationError(
            message=f"Cloudflare Exception - {original_exception.message}",
            llm_provider="cloudflare",
            model=model,
            response=getattr(original_exception, "response", None),
        )
    if "must have required property" in error_str:
        raise BadRequestError(
            message=f"Cloudflare Exception - {original_exception.message}",
            llm_provider="cloudflare",
            model=model,
            response=getattr(original_exception, "response", None),
        )


def _map_cohere_exception(
    *,
    model: str,
    original_exception: _ProviderHTTPException,

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Create a scoped API Token in Cloudflare (My Profile -> API Tokens) with Account -> Workers AI -> Read/Edit permission and use it as api_key
  2. Pass the matching account ID: api_base='https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/v1' or via the model config
  3. Verify the token: curl https://api.cloudflare.com/client/v4/user/tokens/verify -H 'Authorization: Bearer TOKEN'
  4. Rotate the token if it may have leaked, and update env/secret store

Example fix

# before
resp = completion(
    model="cloudflare/@cf/meta/llama-3.1-8b-instruct",
    messages=[...],
    api_key=os.environ["CLOUDFLARE_API_KEY"],  # Global API Key -> rejected
)
# AuthenticationError - Cloudflare Exception - Authentication error

# after: scoped API token + account base
resp = completion(
    model="cloudflare/@cf/meta/llama-3.1-8b-instruct",
    messages=[...],
    api_key=os.environ["CLOUDFLARE_API_TOKEN"],
    api_base=f"https://api.cloudflare.com/client/v4/accounts/{os.environ['CLOUDFLARE_ACCOUNT_ID']}/ai/run/v1",
)
Defensive patterns

Strategy: validation

Validate before calling

import os, re

def cloudflare_token_ok() -> bool:
    tok = (os.environ.get("CLOUDFLARE_API_TOKEN") or "").strip()
    return bool(re.fullmatch(r"[A-Za-z0-9_\-]{30,}", tok))

assert cloudflare_token_ok() and os.environ.get("CLOUDFLARE_ACCOUNT_ID"), (
    "Need CLOUDFLARE_API_TOKEN (scoped, not Global Key) + CLOUDFLARE_ACCOUNT_ID"
)

Try / catch

import litellm

try:
    resp = litellm.completion(model="cloudflare/@cf/meta/llama-3.1-8b-instruct", messages=msgs, api_key=tok)
except litellm.AuthenticationError as e:
    if "Authentication error" in str(e):
        raise PermissionError("Cloudflare token invalid/unscoped — recreate with Workers AI permission") from e
    raise

Prevention

When it happens

Trigger: Calling completion(model='cloudflare/@cf/meta/llama-3.1-8b-instruct', api_key=...) where the api_key is not a valid Cloudflare API token, was created without 'Workers AI:Read' (or Edit) permission, or is a legacy Global API Key where a scoped token is required.

Common situations: Using the account-wide Global API Key instead of a scoped API token; token scoped to the wrong account ID; token revoked in the Cloudflare dashboard but still in env vars; missing CLOUDFLARE_API_TOKEN / wrong account_id in LiteLLM config.

Related errors

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