Queue troubleshooting
Diagnose common Queue setup and runtime problems across local and hosted providers.
Use this page when Queue is wired up but jobs are not behaving the way you expect.
The job never runs
| Likely cause | Fix |
|---|---|
| The queue file is not in the discovery directory. | Put the file in src/queues/** for Vite or server/queues/** for Nitro and Nuxt. |
The queue name in runQueue() does not match the file path. | Check the derived queue name and use that exact string. |
| The provider is misconfigured. | Start with Quickstart and then reapply your provider config. |
The request blocks longer than expected
| Likely cause | Fix |
|---|---|
You are doing work before runQueue() returns. | Move the slow work into the queue handler. |
| You expected the send itself to happen after the response. | Use Defer after response with deferQueue(). |
Local development does not behave like production
| Likely cause | Fix |
|---|---|
| Memory was auto-selected locally. | Set queue.provider explicitly when you want predictable local behavior. |
| You expected retries or durable delivery from Memory. | Switch to a hosted provider. Memory is only for local development and testing. |
Provider-specific callback or binding errors
| Symptom | Fix |
|---|---|
| Cloudflare queue binding is missing. | Check the configured binding name and the Cloudflare deployment setup. |
| Vercel consumers are not firing. | Confirm the queue is deployed on Vercel and review the generated consumer behavior in the Vercel provider guide. |
| Netlify workload events do not match. | Check the configured event name and any config.eventName override. |
| Upstash QStash callbacks fail. | Confirm token, destination, and signature verification settings. |
Validation errors are inconsistent
Validate payloads at both edges:
- before enqueueing with
readValidatedPayload() - inside the handler with
readValidatedJob()
Use Validate payloads for the pattern.
Still stuck
- Re-run the flow with Quickstart and Memory first.
- Compare your setup with the Playground.
- Re-read the provider page for the backend you are using.