{"record":{"id":"687725d42d1c3c6f","repo":"BerriAI/litellm","slug":"cloudflare-exception-original-exception-message","errorCode":null,"errorMessage":"Cloudflare Exception - {original_exception.message}","messagePattern":"Cloudflare Exception - (.+?)","errorType":"exception","errorClass":"AuthenticationError","httpStatus":401,"severity":"critical","filePath":"litellm/litellm_core_utils/exception_mapping_utils.py","lineNumber":1308,"sourceCode":"            raise ServiceUnavailableError(\n                message=f\"{custom_llm_provider.capitalize()}Exception - {error_str}\",\n                llm_provider=custom_llm_provider,\n                model=model,\n            )\n\n\ndef _map_cloudflare_exception(\n    *,\n    model: str,\n    original_exception: _ProviderHTTPException,\n    custom_llm_provider: str,\n    error_str: str,\n    exception_type: str,\n    exception_provider: str,\n    extra_information: str,\n) -> None:\n    if \"Authentication error\" in error_str:\n        raise AuthenticationError(\n            message=f\"Cloudflare Exception - {original_exception.message}\",\n            llm_provider=\"cloudflare\",\n            model=model,\n            response=getattr(original_exception, \"response\", None),\n        )\n    if \"must have required property\" in error_str:\n        raise BadRequestError(\n            message=f\"Cloudflare Exception - {original_exception.message}\",\n            llm_provider=\"cloudflare\",\n            model=model,\n            response=getattr(original_exception, \"response\", None),\n        )\n\n\ndef _map_cohere_exception(\n    *,\n    model: str,\n    original_exception: _ProviderHTTPException,","sourceCodeStart":1290,"sourceCodeEnd":1326,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/exception_mapping_utils.py#L1290-L1326","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create a scoped API Token in Cloudflare (My Profile -> API Tokens) with Account -> Workers AI -> Read/Edit permission and use it as api_key","Pass the matching account ID: api_base='https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/v1' or via the model config","Verify the token: curl https://api.cloudflare.com/client/v4/user/tokens/verify -H 'Authorization: Bearer TOKEN'","Rotate the token if it may have leaked, and update env/secret store"],"exampleFix":"# before\nresp = completion(\n    model=\"cloudflare/@cf/meta/llama-3.1-8b-instruct\",\n    messages=[...],\n    api_key=os.environ[\"CLOUDFLARE_API_KEY\"],  # Global API Key -> rejected\n)\n# AuthenticationError - Cloudflare Exception - Authentication error\n\n# after: scoped API token + account base\nresp = completion(\n    model=\"cloudflare/@cf/meta/llama-3.1-8b-instruct\",\n    messages=[...],\n    api_key=os.environ[\"CLOUDFLARE_API_TOKEN\"],\n    api_base=f\"https://api.cloudflare.com/client/v4/accounts/{os.environ['CLOUDFLARE_ACCOUNT_ID']}/ai/run/v1\",\n)","handlingStrategy":"validation","validationCode":"import os, re\n\ndef cloudflare_token_ok() -> bool:\n    tok = (os.environ.get(\"CLOUDFLARE_API_TOKEN\") or \"\").strip()\n    return bool(re.fullmatch(r\"[A-Za-z0-9_\\-]{30,}\", tok))\n\nassert cloudflare_token_ok() and os.environ.get(\"CLOUDFLARE_ACCOUNT_ID\"), (\n    \"Need CLOUDFLARE_API_TOKEN (scoped, not Global Key) + CLOUDFLARE_ACCOUNT_ID\"\n)","typeGuard":null,"tryCatchPattern":"import litellm\n\ntry:\n    resp = litellm.completion(model=\"cloudflare/@cf/meta/llama-3.1-8b-instruct\", messages=msgs, api_key=tok)\nexcept litellm.AuthenticationError as e:\n    if \"Authentication error\" in str(e):\n        raise PermissionError(\"Cloudflare token invalid/unscoped — recreate with Workers AI permission\") from e\n    raise","preventionTips":["Use scoped API Tokens with Workers AI Read/Edit, never the Global API Key","Pair the token with the correct account_id in api_base","Verify tokens after rotation with /user/tokens/verify"],"tags":["litellm","cloudflare","authentication","api-token","workers-ai"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}