Cloudflare Workers AI Not Working? Fix Binding, Model & Rate Limit Errors

AI binding not configured in wrangler.toml

The AI binding must be declared in wrangler.toml before it can be used in your Worker. Without it, env.AI will be undefined and you'll get a TypeError.

# wrangler.toml — add this block
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[ai]
binding = "AI"

Then in your Worker TypeScript:

export interface Env {
  AI: Ai; // type from @cloudflare/workers-types
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      prompt: 'What is the capital of France?',
    });
    return Response.json(response);
  },
};

Local dev not working — must use --remote flag

Workers AI inference runs on Cloudflare's GPU network, not locally. The standard wrangler dev command doesn't support AI.

# ❌ Won't work — AI binding unavailable locally
wrangler dev

# ✅ Use --remote to run inference on Cloudflare's network
wrangler dev --remote

Wrong model name / model not found

Correct model ID format: @cf/[author]/[model-name]. Common mistake: using just llama-3.1-8b without the @cf/meta/ prefix.

• Text generation: @cf/meta/llama-3.1-8b-instruct (free), @cf/meta/llama-3.3-70b-instruct-fp8-fast (paid)
• Embeddings: @cf/baai/bge-base-en-v1.5, @cf/baai/bge-large-en-v1.5
• Image generation: @cf/black-forest-labs/flux-1-schnell
• Speech to text: @cf/openai/whisper
• Translation: @cf/meta/m2m100-1.2b

Browse the full catalog at developers.cloudflare.com/workers-ai/models/. Some models (like Llama 70B) require the Workers Paid plan.

Rate limit exceeded (neurons/day)

The free tier allows 10,000 neurons/day — roughly 1 neuron per input token for text models. Add KV caching to reduce AI calls for repeated prompts:

// Add KV caching to reduce AI calls
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { prompt } = await request.json() as { prompt: string };
    const cacheKey = `ai:${crypto.subtle ? '' : ''}${btoa(prompt).slice(0, 32)}`;

    // Check cache first
    const cached = await env.KV.get(cacheKey);
    if (cached) return Response.json(JSON.parse(cached));

    // Run inference
    const result = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt });

    // Cache for 1 hour
    await env.KV.put(cacheKey, JSON.stringify(result), { expirationTtl: 3600 });
    return Response.json(result);
  },
};

• Use smaller models: 8B models use fewer neurons per request than 70B models.
• Upgrade plan: Workers Paid ($5/month) unlocks much higher neuron limits.
• Monitor usage: Cloudflare Dashboard → Workers & Pages → Workers AI → Usage tab.

Streaming with SSE

Call the model with stream: true and return the response as a ReadableStream with Content-Type: text/event-stream:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      prompt: 'Write a short story',
      stream: true, // ← enable streaming
    }) as ReadableStream;

    return new Response(response, {
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
      },
    });
  },
};

• Client-side consumption: use EventSource or fetch with a ReadableStream reader to consume the SSE stream.
• Model support: not all models support streaming — check the model's documentation page before enabling stream: true.
• Buffering check: if tokens aren't appearing in the browser, verify that Content-Type is text/event-stream and the response body is not being buffered by a middleware layer.