BerriAI/litellm · error · AuthenticationError

Cloudflare Exception

Error message

Cloudflare Exception - {original_exception.message}

What it means

_map_cloudflare_exception inspects the error string of a Cloudflare Workers AI failure and, when it contains 'Authentication error', raises litellm.AuthenticationError with 'Cloudflare Exception - <original message>'. This means the request reached Cloudflare but the credential was rejected or missing. litellm passes your token via the Authorization header, so the usual cause is a wrong or absent CLOUDFLARE_API_TOKEN / account id.

Solutions

1. Set a valid token: export CLOUDFLARE_API_TOKEN=<API Token> (created under My Profile > API Tokens with Workers AI / Account: Read permissions) and pass the account id in the model string: 'cloudflare/<account_id>/@cf/meta/llama-3.1-8b-instruct'.
2. Verify the token with curl: curl -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" https://api.cloudflare.com/client/v4/user/tokens/verify.
3. If using litellm proxy, check the config.yaml litellm_params.api_key matches the token and the environment of the running server has it.
4. Confirm the token's account scope covers the account id embedded in the model name.

Example fix

# before
resp = litellm.completion(model="cloudflare/@cf/meta/llama-3.1-8b-instruct", messages=msgs)  # AuthenticationError

# after
import os
os.environ["CLOUDFLARE_API_TOKEN"] = "<your-api-token>"
os.environ["CLOUDFLARE_ACCOUNT_ID"] = "<your-account-id>"
resp = litellm.completion(model="cloudflare/<account-id>/@cf/meta/llama-3.1-8b-instruct", messages=msgs)

import os

def validate_cloudflare_creds() -> None:
    token = os.environ.get("CLOUDFLARE_API_TOKEN")
    account = os.environ.get("CLOUDFLARE_ACCOUNT_ID")
    if not token or not account:
        raise RuntimeError("CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must be set")
    import httpx
    r = httpx.get("https://api.cloudflare.com/client/v4/user/tokens/verify",
                 headers={"Authorization": f"Bearer {token}"})
    if r.status_code != 200:
        raise RuntimeError(f"Cloudflare token invalid ({r.status_code}): {r.text}")

import litellm

def is_authentication_error(e: BaseException) -> bool:
    return isinstance(e, litellm.AuthenticationError)

try:
    resp = litellm.completion(model="cloudflare/<acct>/@cf/meta/llama-3.1-8b-instruct", messages=msgs)
except litellm.AuthenticationError as e:
    logger.error("cloudflare auth failed — check CLOUDFLARE_API_TOKEN: %s", e)
    raise  # config error: retrying cannot succeed

When it happens

Trigger: Calling model='cloudflare/<account-id>/<model>' with CLOUDFLARE_API_TOKEN unset, expired, or revoked; using an API Token scoped to a different account than the one in the model string; passing api_key explicitly with a stray space or wrong token type (using a Global API Key instead of a Bearer API Token).

Common situations: New integrations where env vars were set in the shell but not in the deployed environment (Docker/CI), rotating Cloudflare tokens and forgetting to update the secret, copy-pasting the account id from the dashboard with the wrong prefix, or typo'd model route 'cloudflare/<model>' missing the account id segment.

Related errors

• API key is required
• api_key is required for Volcengine authentication
• CohereException
• {e}
• {e}

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

Appendix: 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 77b7c6c40c)