# Workflows diagnostics

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

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

## Errors

| Code | What happened |
| --- | --- |
| [`WORKFLOW_AGENT_NOT_DISCOVERED`](https://vitehub.dev/docs/workflows/diagnostics/workflow_agent_not_discovered) | The Agent Workflow \<name\> is not a discovered Agent, so OpenWorkflow workers cannot run its turns. |

## Published numbered errors

| Code | What happened |
| --- | --- |
| [`WORKFLOW_B0002`](https://vitehub.dev/docs/workflows/diagnostics/workflow_b0002) | Cannot identify the owning Workflow build for \<root\> because its environment does not uniquely match a resolved configuration. |
| [`WORKFLOW_B0003`](https://vitehub.dev/docs/workflows/diagnostics/workflow_b0003) | Agent Workflows need the Agent package, and the project does not resolve `@vite-hub/agent`. |
| [`WORKFLOW_C0001`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0001) | `<label>` must be a non-empty string when provided. |
| [`WORKFLOW_C0002`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0002) | `<label>` must be a string or runtime env declaration. |
| [`WORKFLOW_C0003`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0003) | `<label>` must be a boolean when provided. |
| [`WORKFLOW_C0004`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0004) | `<label>` must be a positive integer when provided. |
| [`WORKFLOW_C0005`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0005) | `workflow.postgres` must be a plain object. |
| [`WORKFLOW_C0006`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0006) | `workflow.sqlite` must be a plain object. |
| [`WORKFLOW_C0007`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0007) | `workflow.worker` must be `false` or a plain object. |
| [`WORKFLOW_C0008`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0008) | `workflow.driver` cannot be inferred for Netlify hosting. Set `workflow.driver` explicitly or disable `workflow`. |
| [`WORKFLOW_C0009`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0009) | Unknown `workflow.driver`: \<driver\>. Expected "cloudflare", "openworkflow", or "vercel". |
| [`WORKFLOW_C0010`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0010) | Workflow step files \<previousName\> and \<name\> both normalize to the `<propertyName>` step property. Rename one file so each step property is unique. |
| [`WORKFLOW_C0011`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0011) | Workflow step file \<name\> normalizes to an empty step property. Rename the file so the step property is non-empty. |
| [`WORKFLOW_C0012`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0012) | `workflow.postgres.url` and `workflow.sqlite.path` cannot both configure OpenWorkflow storage. |
| [`WORKFLOW_C0013`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0013) | `workflow` must be a plain object. |
| [`WORKFLOW_C0014`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0014) | `defineWorkflow()` requires a workflow handler. |
| [`WORKFLOW_C0015`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0015) | `defineWorkflow()` options must be a plain object. |
| [`WORKFLOW_C0016`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0016) | `defineWorkflow()` native entry must be a workflow handler. |
| [`WORKFLOW_C0017`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0017) | `workflow.database` is not supported. Set `workflow.sqlite.path` or `workflow.postgres.url` explicitly. |
| [`WORKFLOW_C0018`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0018) | `defineWorkflow()` requires the Workflow name as its first argument, for example `defineWorkflow("onboard-user", handler)`. |
| [`WORKFLOW_C0019`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0019) | The Workflow at \<discoveredName\> calls `defineWorkflow(<name>)`. Pass \<discoveredName\>, the name that ViteHub reads from its folder or file name. |
| [`WORKFLOW_C0020`](https://vitehub.dev/docs/workflows/diagnostics/workflow_c0020) | `workflow.driver` cannot be inferred for \<hosting\> hosting. ViteHub infers Vercel Workflow only on Vercel. For durable runs, set `workflow: { driver: "openworkflow", sqlite: { path: ".vitehub/data/workflow.sqlite" } }`, or `postgres: { url }` instead of `sqlite`, and call `startOpenWorkflowWorker()` from `@vite-hub/workflow/openworkflow` in a long-lived process. |
| [`WORKFLOW_CLOUDFLARE_RUN_ID_INVALID`](https://vitehub.dev/docs/workflows/diagnostics/workflow_cloudflare_run_id_invalid) | Cloudflare does not accept the run id \<id\>. A Cloudflare instance id starts with a letter, a digit, or `_`, then uses only letters, digits, `-`, and `_`, up to 100 characters. |
| [`WORKFLOW_OPENWORKFLOW_DATABASE_URL_IGNORED`](https://vitehub.dev/docs/workflows/diagnostics/workflow_openworkflow_database_url_ignored) | DATABASE_URL contains a Postgres URL, but OpenWorkflow no longer selects storage from DATABASE_URL alone. Falling back to a local SQLite file would leave existing Postgres runs behind and stop sharing runs between servers. |
| [`WORKFLOW_OPENWORKFLOW_DATABASE_URL_MISSING`](https://vitehub.dev/docs/workflows/diagnostics/workflow_openworkflow_database_url_missing) | OpenWorkflow uses the Postgres Default Database of the app, but that Database has no connection URL outside a request. It connects through PG* environment variables, which OpenWorkflow cannot read. |
| [`WORKFLOW_OPENWORKFLOW_SETUP_CONNECTION_UNAVAILABLE`](https://vitehub.dev/docs/workflows/diagnostics/workflow_openworkflow_setup_connection_unavailable) | OpenWorkflow sets up its Postgres schema on a second connection while this server holds the setup lock on the first. The database gave no second connection in 10 seconds, so the setup did not start. A pool with one connection, or a pool that other traffic fills, does this. The server tries again later. |
| [`WORKFLOW_OPENWORKFLOW_SETUP_LOCK_TIMEOUT`](https://vitehub.dev/docs/workflows/diagnostics/workflow_openworkflow_setup_lock_timeout) | Another server held the OpenWorkflow schema setup lock for \<seconds\> seconds. This server did not start the schema setup. |
| [`WORKFLOW_R0001`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0001) | Cloudflare workflow binding and name overrides are only supported when one workflow is discovered. |
| [`WORKFLOW_R0003`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0003) | Expected \<label\> to contain a JSON record. |
| [`WORKFLOW_R0004`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0004) | Native Vercel workflow entry \<value\> must be colocated with its discovered workflow definition. |
| [`WORKFLOW_R0005`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0005) | Native Vercel Workflow output conflicts with existing unowned Workflow DevKit functions: \<value\>. Build all native Workflow source directories together. |
| [`WORKFLOW_R0006`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0006) | Native Vercel Workflows need workflow, @workflow/builders. A Workflow folder, a `native` entry, or a "use workflow" function makes a Workflow native. Install them in your app with: pnpm add workflow @workflow/builders |
| [`WORKFLOW_R0008`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0008) | Workflow name \<recoveryName\> conflicts with the generated Agent invocation recovery Workflow for \<name\>. |
| [`WORKFLOW_R0009`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0009) | `createWorkflow()` requires a workflow name. |
| [`WORKFLOW_R0010`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0010) | `createWorkflow()` requires a workflow handler. |
| [`WORKFLOW_R0011`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0011) | `createWorkflow()` requires a workflow name. |
| [`WORKFLOW_R0012`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0012) | `createWorkflow()` requires a workflow handler. |
| [`WORKFLOW_R0013`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0013) | `createWorkflow()` options must be an object. |
| [`WORKFLOW_R0014`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0014) | `resumeWorkflow()` requires an opaque signal token. |
| [`WORKFLOW_R0015`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0015) | Missing workflow definition: \<name\> |
| [`WORKFLOW_R0017`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0017) | OpenWorkflow worker requires workflow.driver "openworkflow". |
| [`WORKFLOW_R0018`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0018) | OpenWorkflow SQLite storage requires a local SQLite file path, received \<path\>. |
| [`WORKFLOW_R0019`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0019) | OpenWorkflow SQLite storage received unsupported storage URL \<path\>. |
| [`WORKFLOW_R0020`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0020) | OpenWorkflow runtime requires workflow.driver "openworkflow", received "\<driver\>". |
| [`WORKFLOW_R0021`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0021) | Invalid workflow payload. |
| [`WORKFLOW_R0022`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0022) | Invalid workflow payload schema. |
| [`WORKFLOW_R0023`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0023) | `createWorkflow()` requires a workflow name. |
| [`WORKFLOW_R0024`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0024) | Duplicate workflow name "\<name\>" from inline definitions. |
| [`WORKFLOW_R0025`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0025) | Duplicate workflow name "\<name\>" from inline and discovered definitions. |
| [`WORKFLOW_R0026`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0026) | Vercel Workflow provider returned an invalid \<field\>. |
| [`WORKFLOW_R0027`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0027) | `workflow.database` is not supported. Set `workflow.sqlite.path` or `workflow.postgres.url` explicitly. |
| [`WORKFLOW_R0028`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0028) | `workflow.sqlite.path` must resolve to a non-empty local SQLite path. Check its runtime environment declaration. |
| [`WORKFLOW_R0029`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0029) | `workflow.postgres.url` must resolve to a non-empty Postgres URL. Check its runtime environment declaration. |
| [`WORKFLOW_R0030`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0030) | `workflow.postgres.url` and `workflow.sqlite.path` cannot both configure OpenWorkflow storage. |
| [`WORKFLOW_R0036`](https://vitehub.dev/docs/workflows/diagnostics/workflow_r0036) | The Cloudflare Workflow \<name\> needs the binding \<binding\>, and the Worker has no binding of that name. ViteHub does not run the Workflow inline outside a development server, because an inline run is not durable. |
| [`WORKFLOW_RENAMED_PROVIDER_KEY`](https://vitehub.dev/docs/workflows/diagnostics/workflow_renamed_provider_key) | `workflow.provider` is \<value\>. ViteHub renamed this key to `driver`, and it does not read `provider`, so Workflow would not use the driver you chose. |
| [`WORKFLOW_ROOT_STEP_SLEEP`](https://vitehub.dev/docs/workflows/diagnostics/workflow_root_step_sleep) | The Workflow \<name\> called `context.sleep()` in its root step. Only a folder Workflow can sleep: move it to `server/workflows/<name>/index.ts` and put the work in numbered step files. |
| [`WORKFLOW_SLEEP_DURATION_INVALID`](https://vitehub.dev/docs/workflows/diagnostics/workflow_sleep_duration_invalid) | The Workflow \<name\> called `context.sleep(<value>)`. A sleep takes a duration such as `'30 seconds'` or `'1 day'`, a number of milliseconds that is 0 or more, or a valid `Date`. |
| [`WORKFLOW_START_DELAY_INVALID`](https://vitehub.dev/docs/workflows/diagnostics/workflow_start_delay_invalid) | `startWorkflow()` does not accept the delay \<delay\>. A delay is a number of milliseconds of 0 or more, a duration such as `"30 minutes"` or `"3 days"`, or a valid `Date`. |

## Operation errors

| Code | What happened |
| --- | --- |
| [`WORKFLOW_DEFINITION_NOT_FOUND`](https://vitehub.dev/docs/workflows/diagnostics/workflow_definition_not_found) | Unknown Workflow: \<workflow\>.\<value\> |
| [`WORKFLOW_DISABLED`](https://vitehub.dev/docs/workflows/diagnostics/workflow_disabled) | Workflow is disabled in this runtime. |
| [`WORKFLOW_OPERATION_FAILED`](https://vitehub.dev/docs/workflows/diagnostics/workflow_operation_failed) | The Workflow operation failed. |
| [`WORKFLOW_OPERATION_UNSUPPORTED`](https://vitehub.dev/docs/workflows/diagnostics/workflow_operation_unsupported) | workflow \<operation\> is not supported by the \<provider\> provider. \<note\> |
| [`WORKFLOW_REGISTRY_MISSING`](https://vitehub.dev/docs/workflows/diagnostics/workflow_registry_missing) | Unknown Workflow: \<workflow\>. The runtime has no Workflow registry. |
| [`WORKFLOW_RUN_AMBIGUOUS`](https://vitehub.dev/docs/workflows/diagnostics/workflow_run_ambiguous) | Runs of \<workflows\> have the id \<id\>. |
| [`WORKFLOW_RUN_NOT_FOUND`](https://vitehub.dev/docs/workflows/diagnostics/workflow_run_not_found) | No recorded run has the id \<id\>. |
| [`WORKFLOW_RUN_UNKNOWN`](https://vitehub.dev/docs/workflows/diagnostics/workflow_run_unknown) | Run \<runId\> was not started by `workflow.start` in this runtime. |
| [`WORKFLOW_RUNS_UNAVAILABLE`](https://vitehub.dev/docs/workflows/diagnostics/workflow_runs_unavailable) | This runtime keeps no Workflow run history. Only `vite dev` records runs. |

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

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

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