references/workers-ai/gotchas.md
Workers AI Troubleshooting
Use the actual error, model identifier, integration, and installed versions to choose the relevant reference.
| Symptom or decision | Documentation and checks | |---------------------|--------------------------| | Missing binding or types | Binding configuration and Workers TypeScript; check the environment being run | | Development inference fails | Workers and Wrangler setup; check account access and binding setup | | Unknown model, invalid input, or unexpected response | Open the exact model in the catalog; check its schema, context window, and feature support | | Inference error or retry decision | Error codes and HTTP statuses | | Throttling or concurrency planning | Current limits | | Usage or cost estimate | Current pricing; use the selected model's billing units and expected workload | | Old SDK examples fail | Native binding, AI SDK, or OpenAI compatibility, according to the integration |
Do not copy an error-code mapping, per-request neuron estimate, or context-window range from another model or an older example. Measure latency for the intended workload rather than promising a fixed cold-start or inference time.