# Queue diagnostics

<!-- Generated by docs/modules/diagnostics from the package catalogs. Write a guide in docs/diagnostics/<CODE>.md instead of editing this file. -->

Each Queue error has a stable `code`. Its `docs` link opens the page of that code. This page lists all 41 codes, and [All diagnostics](https://vitehub.dev/docs/reference/diagnostics) lists every primitive.

## Runtime errors

| Code | What happened |
| --- | --- |
| [`QUEUE_PROVIDER_FAILED`](https://vitehub.dev/docs/queue/diagnostics/queue_provider_failed) | The \<provider\> queue provider failed during \<operation\>. |
| [`QUEUE_PROVIDER_INVALID_RESPONSE`](https://vitehub.dev/docs/queue/diagnostics/queue_provider_invalid_response) | The Vercel queue provider accepted the job, but returned an invalid `messageId`. |
| [`QUEUE_UNSUPPORTED_OPTION`](https://vitehub.dev/docs/queue/diagnostics/queue_unsupported_option) | The \<provider\> queue provider does not support the enqueue option \<options\>. |

## Configuration errors

| Code | What happened |
| --- | --- |
| [`QUEUE_BINDING_NOT_FOUND`](https://vitehub.dev/docs/queue/diagnostics/queue_binding_not_found) | The Cloudflare queue binding "\<binding\>" is not in the Worker env. |
| [`QUEUE_DEFINITION_LOAD_FAILED`](https://vitehub.dev/docs/queue/diagnostics/queue_definition_load_failed) | The Queue Definition "\<queue\>" failed to load. |
| [`QUEUE_DEFINITION_NOT_FOUND`](https://vitehub.dev/docs/queue/diagnostics/queue_definition_not_found) (guide) | No Queue Definition has the name "\<queue\>". |
| [`QUEUE_DISABLED`](https://vitehub.dev/docs/queue/diagnostics/queue_disabled) (guide) | Queue is disabled in this runtime. |
| [`QUEUE_DRIVER_MISMATCH`](https://vitehub.dev/docs/queue/diagnostics/queue_driver_mismatch) | The \<expected\> Queue runtime received the \<driver\> driver. |
| [`QUEUE_INVALID_BINDING`](https://vitehub.dev/docs/queue/diagnostics/queue_invalid_binding) | The Cloudflare queue binding does not have `send()` and `sendBatch()`. |
| [`QUEUE_LOCAL_MODE_MISMATCH`](https://vitehub.dev/docs/queue/diagnostics/queue_local_mode_mismatch) | The local Queue directory already has an engine with a different development error disclosure mode. |
| [`QUEUE_MISSING_QUEUE`](https://vitehub.dev/docs/queue/diagnostics/queue_missing_queue) | A direct local queue client needs a `queue` name. |
| [`QUEUE_MISSING_REGION`](https://vitehub.dev/docs/queue/diagnostics/queue_missing_region) (guide) | The installed `@vercel/queue` needs a region, and ViteHub cannot find one. |
| [`QUEUE_MISSING_TOPIC`](https://vitehub.dev/docs/queue/diagnostics/queue_missing_topic) | A direct Vercel queue client needs a `topic`. |
| [`QUEUE_POSTGRES_CLOSING`](https://vitehub.dev/docs/queue/diagnostics/queue_postgres_closing) | The Postgres Queue runtime is shutting down and cannot accept more jobs or connections. |
| [`QUEUE_POSTGRES_INVALID_URL`](https://vitehub.dev/docs/queue/diagnostics/queue_postgres_invalid_url) | \<variable\> is set, and its value is not a `postgres://` or `postgresql://` URL. |
| [`QUEUE_POSTGRES_MISSING_CONNECTION`](https://vitehub.dev/docs/queue/diagnostics/queue_postgres_missing_connection) | The postgres queue provider uses the connection of the Database "\<database\>", and that Database has no Postgres client in this runtime. |
| [`QUEUE_RUNTIME_NOT_INSTALLED`](https://vitehub.dev/docs/queue/diagnostics/queue_runtime_not_installed) | The Queue runtime has no client factory. The generated server output installs it. |
| [`QUEUE_VERCEL_SDK_INVALID`](https://vitehub.dev/docs/queue/diagnostics/queue_vercel_sdk_invalid) | `@vercel/queue` does not have the client API that ViteHub uses. |
| [`QUEUE_VERCEL_SDK_UNAVAILABLE`](https://vitehub.dev/docs/queue/diagnostics/queue_vercel_sdk_unavailable) | `@vercel/queue` or `@vercel/functions` cannot be loaded. |

## Definition and build errors

| Code | What happened |
| --- | --- |
| [`QUEUE_BINDING_CONFLICT`](https://vitehub.dev/docs/queue/diagnostics/queue_binding_conflict) | A custom `queue.binding` works with one Queue Definition only, and this app has more. |
| [`QUEUE_CONTRIBUTION_INVALID`](https://vitehub.dev/docs/queue/diagnostics/queue_contribution_invalid) | See the page of the code. |
| [`QUEUE_CRYPTO_UNAVAILABLE`](https://vitehub.dev/docs/queue/diagnostics/queue_crypto_unavailable) | Cloudflare queue names for long Queue Definition names need the `node:crypto` module, and this runtime does not have it. |
| [`QUEUE_DEFINITION_DUPLICATE`](https://vitehub.dev/docs/queue/diagnostics/queue_definition_duplicate) | Queue "\<name\>" is defined more than once:   - \<handler\>   - \<contribution\> Rename or remove one definition. Each Queue name must have one definition. |
| [`QUEUE_DEFINITIONS_CHANGED`](https://vitehub.dev/docs/queue/diagnostics/queue_definitions_changed) | The \<context\> Queue Definitions changed after Vite resolved the config. |
| [`QUEUE_INVALID_CONFIG`](https://vitehub.dev/docs/queue/diagnostics/queue_invalid_config) | `queue` must be a plain object or `false`. |
| [`QUEUE_INVALID_DEFINITION`](https://vitehub.dev/docs/queue/diagnostics/queue_invalid_definition) | `defineQueue()` needs a handler function. |
| [`QUEUE_INVALID_DRIVER`](https://vitehub.dev/docs/queue/diagnostics/queue_invalid_driver) | `queue.driver` "\<driver\>" is not a Queue driver. |
| [`QUEUE_INVALID_NAME`](https://vitehub.dev/docs/queue/diagnostics/queue_invalid_name) | The Cloudflare queue name "\<name\>" can contain only letters, numbers, and dashes, and must start and end with a letter or number. |
| [`QUEUE_MISSING_DRIVER`](https://vitehub.dev/docs/queue/diagnostics/queue_missing_driver) | ViteHub cannot select a Queue driver for \<hosting\> hosting. |
| [`QUEUE_NAME_COLLISION`](https://vitehub.dev/docs/queue/diagnostics/queue_name_collision) | The Queue Definitions "\<first\>" and "\<second\>" have the same provider name "\<resolved\>". |
| [`QUEUE_PLUGIN_INCOMPATIBLE`](https://vitehub.dev/docs/queue/diagnostics/queue_plugin_incompatible) | The `hubQueue()` plugin in the Vite config does not expose the Queue Nitro config. |
| [`QUEUE_PROVISION_FAILED`](https://vitehub.dev/docs/queue/diagnostics/queue_provision_failed) | Cloudflare returned an invalid queue list during provisioning. |
| [`QUEUE_RENAMED_PROVIDER_KEY`](https://vitehub.dev/docs/queue/diagnostics/queue_renamed_provider_key) | `queue.provider` is \<value\>. ViteHub renamed this key to `driver`, and it does not read `provider`, so Queue would not use the driver you chose. |

## Operation errors

| Code | What happened |
| --- | --- |
| [`QUEUE_DEFINITION_NAME_INVALID`](https://vitehub.dev/docs/queue/diagnostics/queue_definition_name_invalid) | The queue name is not a valid Queue Definition name. |
| [`QUEUE_JOB_DUPLICATE`](https://vitehub.dev/docs/queue/diagnostics/queue_job_duplicate) | A newer pending or running job has the idempotency key of this dead job, so the dead job cannot run again. |
| [`QUEUE_JOB_NOT_FOUND`](https://vitehub.dev/docs/queue/diagnostics/queue_job_not_found) | No stored job has this message ID. The local and postgres drivers delete a job when its handler succeeds. |
| [`QUEUE_JOB_RUNNING`](https://vitehub.dev/docs/queue/diagnostics/queue_job_running) | The job is running now. |
| [`QUEUE_JOBS_UNAVAILABLE`](https://vitehub.dev/docs/queue/diagnostics/queue_jobs_unavailable) | The \<driver\> queue driver does not let the app read its jobs. Only the local and postgres drivers store jobs that ViteHub can list. |

## Provider cause errors

| Code | What happened |
| --- | --- |
| [`QUEUE_LOCAL_LIMIT_EXCEEDED`](https://vitehub.dev/docs/queue/diagnostics/queue_local_limit_exceeded) | \<provider\> accepts `retentionSeconds` from \<min\> to \<max\>, got \<value\>. |
| [`QUEUE_VERCEL_BATCH_REJECTED`](https://vitehub.dev/docs/queue/diagnostics/queue_vercel_batch_rejected) | @vercel/queue did not accept \<failed\> of \<total\> batch messages. |
| [`QUEUE_VERCEL_SEND_BATCH_UNAVAILABLE`](https://vitehub.dev/docs/queue/diagnostics/queue_vercel_send_batch_unavailable) | The Vercel queue client has no `sendBatch()`. Install `@vercel/queue` 0.10 or later. |

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/queue.md)
- [Get started](https://vitehub.dev/raw/docs/queue/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/queue/configure.md)
- [Server API](https://vitehub.dev/raw/docs/queue/server-api.md)
- [Hosts](https://vitehub.dev/raw/docs/queue/hosts.md)
- [Limits and errors](https://vitehub.dev/raw/docs/queue/limits-and-errors.md)
- [Concepts](https://vitehub.dev/raw/docs/queue/concepts.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
