{"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":"error","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/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/litellm_core_utils/exception_mapping_utils.py#L1290-L1326","documentation":"_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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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'.","Verify the token with curl: curl -H \"Authorization: Bearer $CLOUDFLARE_API_TOKEN\" https://api.cloudflare.com/client/v4/user/tokens/verify.","If using litellm proxy, check the config.yaml litellm_params.api_key matches the token and the environment of the running server has it.","Confirm the token's account scope covers the account id embedded in the model name."],"exampleFix":"# before\nresp = litellm.completion(model=\"cloudflare/@cf/meta/llama-3.1-8b-instruct\", messages=msgs)  # AuthenticationError\n\n# after\nimport os\nos.environ[\"CLOUDFLARE_API_TOKEN\"] = \"<your-api-token>\"\nos.environ[\"CLOUDFLARE_ACCOUNT_ID\"] = \"<your-account-id>\"\nresp = litellm.completion(model=\"cloudflare/<account-id>/@cf/meta/llama-3.1-8b-instruct\", messages=msgs)","handlingStrategy":"validation","validationCode":"import os\n\ndef validate_cloudflare_creds() -> None:\n    token = os.environ.get(\"CLOUDFLARE_API_TOKEN\")\n    account = os.environ.get(\"CLOUDFLARE_ACCOUNT_ID\")\n    if not token or not account:\n        raise RuntimeError(\"CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must be set\")\n    import httpx\n    r = httpx.get(\"https://api.cloudflare.com/client/v4/user/tokens/verify\",\n                 headers={\"Authorization\": f\"Bearer {token}\"})\n    if r.status_code != 200:\n        raise RuntimeError(f\"Cloudflare token invalid ({r.status_code}): {r.text}\")","typeGuard":"import litellm\n\ndef is_authentication_error(e: BaseException) -> bool:\n    return isinstance(e, litellm.AuthenticationError)","tryCatchPattern":"try:\n    resp = litellm.completion(model=\"cloudflare/<acct>/@cf/meta/llama-3.1-8b-instruct\", messages=msgs)\nexcept litellm.AuthenticationError as e:\n    logger.error(\"cloudflare auth failed — check CLOUDFLARE_API_TOKEN: %s\", e)\n    raise  # config error: retrying cannot succeed","preventionTips":["Fail fast at startup by verifying CLOUDFLARE_API_TOKEN via the tokens/verify endpoint before serving traffic.","Store the token in a secret manager; never hardcode it in model configs checked into git.","Scope the token to exactly one account with Workers AI permissions and rotate on a schedule.","Include the account id in the model string from the same config source as the token so they can't diverge."],"tags":["litellm","cloudflare","workers-ai","authentication","api-token"],"backgroundTag":"invalid-api-key","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}