# QUEUE_DEFINITION_NOT_FOUND

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

`sendQueue()`, `useQueue()`, or `dynamicQueue` throws `QUEUE_DEFINITION_NOT_FOUND` when the runtime has no Queue Definition with the name that you passed. `error.why` shows the name only when it is a safe identifier.

## Why it happens

The generated server output loads a registry of the discovered Queue Definitions. ViteHub looks up the name in that registry. The lookup fails when:

- No file defines the name. ViteHub discovers `server/queues/<name>.ts` and `src/<name>.queue.ts`. The file path gives the name, so `server/queues/welcome-email.ts` is `welcome-email`.
- The file has no default export of `defineQueue()`. A named export is not a Queue Definition.
- Queue is not enabled. Without `queue: true` in `vitehub()`, ViteHub generates no registry, so every name is unknown.
- The code runs outside of the generated server output, for example a script that you start with plain `node`. Only the server output loads the registry.
- The local provider runs a stored job, but you renamed or deleted its Queue Definition. The job becomes a dead job.
- The Cloudflare Worker receives a batch from a queue that maps to no Queue Definition of this build.

## Fix it

```diff [server/api/signup.post.ts]
 import { sendQueue } from 'vite-hub/queue'

 export default defineEventHandler(async () => {
-  const [error] = await sendQueue('welcome', { email: 'ava@example.com' })
+  const [error] = await sendQueue('welcome-email', { email: 'ava@example.com' })
   if (error) throw error
 })
```

Use the name that discovery gives the file. Here the file is `server/queues/welcome-email.ts`, and it has `export default defineQueue(...)`.

```diff [vite.config.ts]
 export default defineConfig({
-  plugins: [vitehub({ host: 'cloudflare' })],
+  plugins: [vitehub({ host: 'cloudflare', queue: true })],
 })
```

Enable Queue when the Queue Definition exists but every name fails. Restart `vite dev`, or build again, so the server output loads the registry.

For a dead local job of a deleted Queue Definition, run `vitehub queue jobs clear --state dead`.

## Check the fix

Run `vitehub inspect definitions --kind queue`. It lists each discovered Queue Definition with its name and file. If it prints `Unknown Definition kind: queue`, Queue is not enabled. Then start `vite dev` and call the route again.

## Related

- [Define a queue](https://vitehub.dev/docs/queue/configure#define-a-queue)
- [Queue Server API](https://vitehub.dev/docs/queue/server-api)
- [Inspect Definitions and Provider Output](https://vitehub.dev/docs/development/cli#inspect-definitions-and-provider-output)
- [Local delivery](https://vitehub.dev/docs/queue/limits-and-errors#local-delivery)
- [`QUEUE_DISABLED`](https://vitehub.dev/docs/queue/diagnostics/queue_disabled)
- [`QUEUE_DEFINITION_LOAD_FAILED`](https://vitehub.dev/docs/queue/diagnostics/queue_definition_load_failed)

## Source

`QUEUE_DEFINITION_NOT_FOUND` belongs to the `queue` package. Its catalog entry is in [`src/error-diagnostics.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/queue/src/error-diagnostics.ts#L82). It is raised in [`src/internal/runtime/cloudflare-vite.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/queue/src/internal/runtime/cloudflare-vite.ts#L84), [`src/internal/runtime/cloudflare-vite.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/queue/src/internal/runtime/cloudflare-vite.ts#L88), [`src/internal/runtime/state.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/queue/src/internal/runtime/state.ts#L22), [`src/runtime/client.ts`](https://github.com/vite-hub/vitehub/blob/main/packages/queue/src/runtime/client.ts#L99).

See [all Queue diagnostics](https://vitehub.dev/docs/queue/diagnostics).

<!-- 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)

Next: [Hosts](https://vitehub.dev/raw/docs/queue/hosts.md)

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