Skip to content

Troubleshooting

Common errors from the Workers AI provider, with causes and fixes.

Updated

Most headings are the start of the error message or the exception name.

Setup errors

Workers AI requires an API token

Cause. key is empty or not a string. Fix. Set key in your provider config, for example env('CLOUDFLARE_AI_API_TOKEN'). Create the token with the permission named Account > Workers AI > Read in the Cloudflare dashboard.

Workers AI requires an account_id or explicit url

Cause. The config has neither account_id nor url. Fix. Set CLOUDFLARE_ACCOUNT_ID, or set url.

Workers AI config has both url and account_id set

Cause. The package can’t tell which one you mean. Fix. Remove one. Use url for full control, or account_id with an optional gateway.

account_id looks like a URL, or gateway looks malformed

Cause. You pasted a URL or a path into the field. Fix. Use only the 32-character account ID. Use only the gateway slug.

Undefined array key “driver”

Cause. The provider entry in config/ai.php has no driver value. Fix. Add 'driver' => 'workers-ai' to the entry.

RequestException: HTTP request returned status code 401

The end of the message tells you which credential failed. A bad API token ends with {"code":10000,"message":"Authentication error"}, and an authenticated gateway that rejects the request returns {"code":2009,"message":"Unauthorized"}. The exception is Illuminate\Http\Client\RequestException, not AiException.

Cause. One of these:

  • The API token is wrong or lacks the Account > Workers AI > Read permission.
  • Your AI Gateway has Authenticated Gateway on, and you didn’t set gateway_token. This affects chat and embeddings; Clef and Clairic don’t need it.
  • You use the gateway provider path workers-ai/v1 for embeddings on a gateway with Authenticated Gateway on.

Fix. Check the token. Set gateway_token to an AI Gateway token with Run permission. For embeddings, remove gateway_path to use /compat.

Model errors

The model has the workers-ai/ prefix, but the endpoint expects bare model IDs

Cause. You wrote workers-ai/@cf/..., and the endpoint is the direct API or the provider path, so the package throws InvalidArgumentException. A third-party name such as openai/gpt-5.5 doesn’t cause this error. Fix. Drop the prefix. Write @cf/....

410 Model has been deprecated (RequestException)

Cause. Cloudflare retired the model. Fix. Pick another model. @cf/meta/llama-3.1-8b-instruct is retired.

403 This account is not allowed to access (RequestException)

Cause. Your account or plan does not include the model. Fix. Use a model your account can use.

Answer problems

EmptyResponseException

Cause. The model returned HTTP 200 with no text and no tool calls. Usually that means a reasoning model spent its whole token cap on thinking. Fix. Raise the token cap with #[MaxTokens] or default_max_tokens. Lower reasoning_effort. Raise #[Timeout] if you raise the cap.

TruncatedResponseException

Cause. The answer reached the token cap, and throw_on_truncation is on. Fix. Raise the token cap, or lower reasoning_effort so less of the cap goes to thinking.

The answer stops at about 256 tokens

Cause. The request had no token cap, so Cloudflare used its default of 256. Fix. Don’t set default_max_tokens to null. Leave the 4096 default, or set a number.

The answer is empty, and no exception is thrown

Cause. throw_on_empty_response is false. Fix. Set it to true, or check $response->text yourself.

The model describes the tool in text and does not call it

Cause. The model doesn’t call tools, or chose not to. The default model doesn’t call tools on the /v1 endpoint. Fix. Use a model that calls tools, such as @cf/openai/gpt-oss-120b. To force a call, return ['tool_choice' => 'required'] from providerOptions().

Structured output is missing fields

Cause. Workers AI’s JSON mode is best-effort, and the package re-asks only up to 2 times by default. Fix. Add #[Strict]. Raise structured_output_retries. Lower reasoning_effort. Raise the token cap.

Workers AI reasoning_effort must be one of: low, medium, high

Cause. You used none, minimal or another value. Fix. Use low, medium or high.

Timeouts and rate limits

Connection timeout after 60 seconds

Cause. The request ran longer than the Laravel AI timeout, and the package doesn’t retry timeouts. Fix. Raise #[Timeout]. Lower the token cap or reasoning_effort.

GatewayTimeoutException (HTTP 408)

Cause. The generation ran longer than the gateway is willing to wait. This isn’t a client timeout. Fix. Lower the token cap. Lower reasoning_effort. Split the work. Configure a failover provider.

RateLimitedException (HTTP 429)

Cause. You sent more requests than your account or model allows, and the package’s retries didn’t get through. Fix. Send fewer requests at once. If the limit only lasts a moment, raise retry_attempts.

ProviderOverloadedException

Cause. Cloudflare returned 502, 503, 504, 520, 522 or 524 on every attempt. Fix. Try again later. Configure a failover provider.

A request takes much longer than the timeout

Cause. Your AI Gateway retries inside the request, and the package retries on top of that. Fix. Use one retry layer. See Errors and retries.

Clef and Clairic errors

Workers AI Error: Response contained no answers.

Cause. Cloudflare returned HTTP 200 with no answers. Fix. Check the model ID and your questions or fields. If they’re correct, try again, and report the issue if it keeps happening.

Workers AI Error: [type] message, from Clef or Clairic

Cause. Cloudflare returned HTTP 200 with a non-empty errors, or success: false. Fix. Read the message, which holds Cloudflare’s reason.

Clef, Clairic, images, audio, transcription and reranking use the Workers AI /ai/run API

Cause. Your url ends in /compat. Fix. Set account_id, and gateway if you use one. Remove url.

Attachment errors

Workers AI chat models do not read document attachments

Cause. You attached a document, and convert_documents is off. Fix. Set convert_documents to true on the provider entry, or call Markdown::of(). See Documents.

Workers AI chat models do not accept audio or video attachments

Cause. You attached an audio or video file to a chat call. Fix. Use Transcription::of() for speech. See Speech and transcription.

Unsupported attachment type

Cause. The attachment is not a Laravel AI File or an uploaded file. Fix. Create the attachment with Image::fromPath(), Image::fromUrl() or a similar method.

Cost shows as zero

Cause. You read usage.neurons from $response->raw, and raw is null. This happens on laravel/ai 0.9, and on streamed calls.

Fix. Listen for WorkersAiUsageReported. It fires for streamed calls too. See Cost tracking.

Media and search errors

Input prompt contains NSFW content

Cause. Cloudflare’s content filter rejected the image prompt. It sometimes flags harmless ones. Fix. Reword the prompt, or try another model.

Workers AI model has a fixed size

Cause. You set a size on flux-1-schnell, which rejects width and height. Fix. Remove the size, or use a FLUX.2 model.

Workers AI model cannot run through AI Gateway

Cause. You called nova-3 with a gateway set, and Cloudflare’s REST API rejects its audio body through a gateway. Fix. Use a provider entry with no gateway for that call, or use whisper-large-v3-turbo. See Non-JSON models.

Workers AI model does not label speakers

Cause. You called diarize() on a Whisper model. Fix. Use @cf/deepgram/nova-3.

Web search failed. No provider key is configured on this gateway

Cause. That gateway can’t bill the search and has no stored key for it. Fix. Use the tool’s default gateway, default, or store a key on the named gateway. See Web search.

The model ignores Laravel AI’s WebSearch tool

Cause. Workers AI can’t run provider tools, and on laravel/ai 1.1 and later, Laravel AI removes them with no error. Fix. Use CloudflareWebSearch. See Web search.

Upgrade errors

composer cannot resolve laravel/ai

Cause. Your project requires laravel/ai ^0.7 or ^0.8. Package ^1.0 needs laravel/ai ^0.9 to ^1.3. Fix. Bump both packages in one command:

composer require "laravel/ai:^1.0" "meirdick/laravel-cf-workersai:^1.0" -W

table agent_conversations has no column named participant_type

Cause. The laravel/ai database schema changed between 0.9 and 0.11. This package isn’t involved. Fix. Publish the laravel/ai migrations again, or reconcile them.

Your composer.json says PHP 8.2

Cause. This package needs PHP 8.3. Composer checks the PHP you run, not the minimum you declare. Fix. Set your own php constraint to ^8.3.

Type to search…

↑↓ navigate↵ selectEsc close