---
title: "Troubleshooting"
description: "Common errors from the Workers AI provider, with causes and fixes."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai-docs.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

## 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 cannot pick between them.
**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 in 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

A bad API token ends with `{"code":10000,"message":"Authentication error"}`. 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 did not set `gateway_token`. This affects chat and embeddings. Clef and Clairic do not 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. The package throws `InvalidArgumentException`. A third-party name such as `openai/gpt-5.5` does not 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 a reasoning model used 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. 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 and Cloudflare used its default.
**Fix.** Do not 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 does not call tools, or chose not to. The default model does not 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 JSON mode is best-effort. The package re-asks 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. The package does not retry this.
**Fix.** Raise `#[Timeout]`. Lower the token cap or `reasoning_effort`.

### GatewayTimeoutException (HTTP 408)

**Cause.** The generation ran longer than the gateway waits. This is not 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. The package already retried.
**Fix.** Limit your concurrency. Raise `retry_attempts` if the limit is brief.

### 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 too.
**Fix.** Use one retry layer. See [Errors and retries](/docs/guides/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 are correct, try again, and report the issue if it continues.

### 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. It holds the Cloudflare 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](/docs/guides/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](/docs/guides/audio/).

### 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.** One of these:

- 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](/docs/guides/cost-tracking/).

## Media and search errors

### Input prompt contains NSFW content

**Cause.** Cloudflare's content filter rejected the image prompt. It can flag harmless prompts.
**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. 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](/docs/concepts/routes/#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 cannot 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](/docs/guides/web-search/).

### The model ignores Laravel AI's WebSearch tool

**Cause.** Workers AI cannot run provider tools. On `laravel/ai` 1.1 and later, Laravel AI removes them with no error.
**Fix.** Use `CloudflareWebSearch`. See [Web search](/docs/guides/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:

```bash
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. The cause is not this package.
**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 your declared minimum.
**Fix.** Set your own `php` constraint to `^8.3`.

Source: https://laravel-cf-workersai-docs.mdick85.workers.dev/docs/troubleshooting/index.mdx