# Workspace diagnostics

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

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

## Configuration errors

| Code | What happened |
| --- | --- |
| [`WORKSPACE_RENAMED_STORE_PROVIDER_KEY`](https://vitehub.dev/docs/workspace/diagnostics/workspace_renamed_store_provider_key) | The Workspace `store` sets `provider: <provider>`. ViteHub renamed this key to `driver`, and it does not read `provider`, so the Store would not be the one you chose. |
| [`WORKSPACE_UNKNOWN_STORE_DRIVER`](https://vitehub.dev/docs/workspace/diagnostics/workspace_unknown_store_driver) | The Workspace `store.driver` is \<driver\>. ViteHub renamed this driver to "\<renamed\>", and it does not read \<driver\>. |

## Published numbered errors

| Code | What happened |
| --- | --- |
| [`WORKSPACE_B0001`](https://vitehub.dev/docs/workspace/diagnostics/workspace_b0001) | Workspace definition "\<name\>" has no \<value\>. |
| [`WORKSPACE_B0002`](https://vitehub.dev/docs/workspace/diagnostics/workspace_b0002) | Workspace config "\<file\>" must use defineWorkspace(); defineAgent() belongs in server/agents/\<name\>/agent.ts. |
| [`WORKSPACE_B0003`](https://vitehub.dev/docs/workspace/diagnostics/workspace_b0003) | Workspace "\<name\>" is defined more than once:   - \<first\>   - \<contribution\> Rename or remove one definition. Each Workspace name must have one definition. |
| [`WORKSPACE_B0004`](https://vitehub.dev/docs/workspace/diagnostics/workspace_b0004) | See the page of the code. |
| [`WORKSPACE_B0005`](https://vitehub.dev/docs/workspace/diagnostics/workspace_b0005) | Workspace "\<name\>" sets a store that may need a Cloudflare Artifacts binding, but the build cannot load \<definitionFile\> to read it: \<value\> |
| [`WORKSPACE_C0001`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0001) | `workspace` must be a plain object. |
| [`WORKSPACE_C0002`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0002) | workspace config does not support option\<value\>: \<value\>. |
| [`WORKSPACE_C0003`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0003) | Workspace Scope source grant "\<key\>" is request-only without a Source Request descriptor. |
| [`WORKSPACE_C0004`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0004) | Workspace Scope source grant "\<key\>" is root-mounted; grant explicit paths instead. |
| [`WORKSPACE_C0005`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0005) | Workspace source configuration is ambiguous. Matched \<value\>. A Source helper call, for example github(...) or custom(...), makes the source kind explicit. |
| [`WORKSPACE_C0006`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0006) | file requires a path or workspacePath. |
| [`WORKSPACE_C0007`](https://vitehub.dev/docs/workspace/diagnostics/workspace_c0007) | fetch() requires an explicit path when the URL includes query parameters. |
| [`WORKSPACE_R0001`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0001) | Workspace root is not a valid mutation target. |
| [`WORKSPACE_R0002`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0002) | createWorkspaceTools requires at least one enabled workspace operation. |
| [`WORKSPACE_R0003`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0003) | Write operations require a mutable Workspace. A useWorkspace(name, { mode: "write" }).tools.write() call provides one. |
| [`WORKSPACE_R0004`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0004) | Missing value for \<flag\>. |
| [`WORKSPACE_R0005`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0005) | See the page of the code. |
| [`WORKSPACE_R0006`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0006) | See the page of the code. |
| [`WORKSPACE_R0007`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0007) | Unknown option: \<arg\>. |
| [`WORKSPACE_R0008`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0008) | workspace dev exec requires a command. |
| [`WORKSPACE_R0009`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0009) | Unexpected argument: \<arg\>. Use exec \<command...\> for one-shot commands. |
| [`WORKSPACE_R0015`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0015) | defineWorkspace does not support option\<value\>: \<value\>. |
| [`WORKSPACE_R0016`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0016) | defineWorkspace requires a workspace definition. |
| [`WORKSPACE_R0017`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0017) | Workspace names are inferred from definition filenames. |
| [`WORKSPACE_R0018`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0018) | Workspace glob accepts at most \<maxPatterns\> model-facing patterns. |
| [`WORKSPACE_R0019`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0019) | Workspace glob pattern input exceeds the model-facing limit of \<maxBytes\> bytes. |
| [`WORKSPACE_R0020`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0020) | Workspace glob pattern complexity exceeds the model-facing limit of \<maxComplexity\> expansions. |
| [`WORKSPACE_R0021`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0021) | Workspace definition "\<name\>" must not declare a name. Workspace names are inferred from filenames. |
| [`WORKSPACE_R0022`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0022) | registerWorkspacePlugin requires a Workspace name. |
| [`WORKSPACE_R0023`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0023) | Invalid workspace rule maxBytes value "\<value\>". |
| [`WORKSPACE_R0024`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0024) | Workspace plugins require an id. |
| [`WORKSPACE_R0025`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0025) | No API-backed Source request executor is available for this workspace. |
| [`WORKSPACE_R0026`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0026) | Workspace Store does not support rebasing. |
| [`WORKSPACE_R0027`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0027) | Cloudflare Artifacts binding "\<binding\>" already exists in Wrangler config with namespace \<namespace\>, but Workspace requested namespace "\<namespace\>". Configure a unique binding or use the existing namespace. |
| [`WORKSPACE_R0028`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0028) | See the page of the code. |
| [`WORKSPACE_R0029`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0029) | Cloudflare Artifacts binding "\<binding\>" cannot use both namespace "\<namespace\>" and "\<namespace\>". Configure a unique binding for each namespace. |
| [`WORKSPACE_R0033`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0033) | Unexpected Vercel Blob list response. |
| [`WORKSPACE_R0034`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0034) | Workspace preparation requires a Workspace name. |
| [`WORKSPACE_R0035`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0035) | Workspace preparation sources must be non-empty strings. |
| [`WORKSPACE_R0036`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0036) | Workspace preparation retryDelayMs must be between 0 and \<MAX_TIMER_DELAY_MS\>. |
| [`WORKSPACE_R0037`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0037) | Workspace "\<workspaceName\>" has no startup sources to prepare. |
| [`WORKSPACE_R0038`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0038) | Workspace "\<workspaceName\>" sources failed to prepare: \<value\>. |
| [`WORKSPACE_R0039`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0039) | Workspace "\<workspaceName\>" preparation stopped. |
| [`WORKSPACE_R0040`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0040) | Workspace Dev command cannot be empty. |
| [`WORKSPACE_R0041`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0041) | Workspace Dev command requires a Workspace Session. |
| [`WORKSPACE_R0042`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0042) | Workspace Dev Session did not start. |
| [`WORKSPACE_R0043`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0043) | Workspace Dev Session did not start. |
| [`WORKSPACE_R0044`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0044) | See the page of the code. |
| [`WORKSPACE_R0045`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0045) | Workspace session host must declare executionAuthority. |
| [`WORKSPACE_R0046`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0046) | Request-only fetch source does not expose a default Source-Backed Path. |
| [`WORKSPACE_R0047`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0047) | Fetch source item does not exist: \<sourcePath\>. |
| [`WORKSPACE_R0048`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0048) | fetch() resolver did not resolve before reading \<key\>. |
| [`WORKSPACE_R0049`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0049) | fetch() responseType "\<responseType\>" is not supported in v1. Use json or text. |
| [`WORKSPACE_R0050`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0050) | fetch() method "\<label\>" is not supported in v1. Use GET, HEAD, or POST. |
| [`WORKSPACE_R0051`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0051) | fetch() accepts either query or querySchema, not both. |
| [`WORKSPACE_R0052`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0052) | fetch() accepts either body or bodySchema, not both. |
| [`WORKSPACE_R0053`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0053) | fetch() \<method\> requests cannot declare body or bodySchema. |
| [`WORKSPACE_R0054`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0054) | fetch() \<option\> must expose a Standard JSON Schema-compatible input projection. |
| [`WORKSPACE_R0055`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0055) | Source request method \<method\> does not match declared method \<method\>. |
| [`WORKSPACE_R0056`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0056) | Source request URL does not match the declared Source target. |
| [`WORKSPACE_R0057`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0057) | Source request query does not match the declared Source request shape. |
| [`WORKSPACE_R0058`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0058) | Source request body does not match the declared Source request shape. |
| [`WORKSPACE_R0059`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0059) | Source request does not declare a body. |
| [`WORKSPACE_R0060`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0060) | github() resolver did not resolve before reading \<key\>. |
| [`WORKSPACE_R0061`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0061) | github() resolver requires repo or typed pullRequest source context. |
| [`WORKSPACE_R0063`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0063) | See the page of the code. |
| [`WORKSPACE_R0064`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0064) | Source request executor is unavailable. |
| [`WORKSPACE_R0065`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0065) | \<code\>: \<path\> |
| [`WORKSPACE_R0066`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0066) | Missing Vercel Blob credentials for Workspace storage. Connect a Blob store to the Vercel project so it gets `BLOB_STORE_ID`, or set `BLOB_READ_WRITE_TOKEN` off Vercel. |
| [`WORKSPACE_R0069`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0069) | This Workspace Store does not support retained history. Configure a Store with the history capability. |
| [`WORKSPACE_R0070`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0070) | History cursor does not belong to ref "\<ref\>". |
| [`WORKSPACE_R0071`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0071) | Invalid history ref\<value\>. Use up to 128 letters, numbers, underscores, and dashes, separated by single dots or slashes. |
| [`WORKSPACE_R0072`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0072) | GitHub workspace store requires \<label\>.\<value\> |
| [`WORKSPACE_R0073`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0073) | GitHub history commit \<what\> is \<size\> bytes, over the limit of \<max\>. Shorten it. |
| [`WORKSPACE_R0074`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0074) | Cannot retry interrupted removal without a file revision: \<path\>. Inspect the file and remove it explicitly if cleanup is still needed. |
| [`WORKSPACE_R0075`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0075) | Workspace rule "\<pattern\>" sets read. Workspace rules do not limit reads. |
| [`WORKSPACE_R0076`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0076) | Workspace rule "\<pattern\>" does not support option "\<key\>". |
| [`WORKSPACE_R0077`](https://vitehub.dev/docs/workspace/diagnostics/workspace_r0077) | The `database` of the Blob + Database Store for workspace "\<workspace\>" is not a Drizzle database. |

## Checkout errors

| Code | What happened |
| --- | --- |
| [`WORKSPACE_CHECKOUT_CONFLICT`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_conflict) | Workspace "\<workspace\>" has unresolved conflicts: \<conflicted\>. |
| [`WORKSPACE_CHECKOUT_DIR`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_dir) | The checkout folder "\<dir\>" must be a folder inside the project, not the project root. |
| [`WORKSPACE_CHECKOUT_FAILED`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_failed) | See the page of the code. |
| [`WORKSPACE_CHECKOUT_MISSING`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_missing) | Workspace "\<workspace\>" is not checked out. |
| [`WORKSPACE_CHECKOUT_OPTIONS`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_options) | Workspace "\<workspace\>" is checked out with \<key\> "\<expected\>", not "\<actual\>". |
| [`WORKSPACE_CHECKOUT_OVERLAP`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_overlap) | Workspace "\<workspace\>" folder "\<dir\>" overlaps Workspace "\<other\>" folder "\<otherDir\>". |
| [`WORKSPACE_CHECKOUT_PATH`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_path) | The checkout paths "\<other\>" and "\<path\>" use different spellings for one file-system path, or replace a file with a directory. |
| [`WORKSPACE_CHECKOUT_SYMLINK`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_symlink) | \<path\> is a symbolic link. A checkout reads and writes only real files and folders. |
| [`WORKSPACE_CHECKOUT_TOO_LARGE`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_too_large) | The push of Workspace "\<workspace\>" is \<size\>, over the \<limit\> limit of one push.\<value\> |
| [`WORKSPACE_CHECKOUT_USAGE`](https://vitehub.dev/docs/workspace/diagnostics/workspace_checkout_usage) | \<command\> accepts at most one Workspace name. |
| [`WORKSPACE_LOCK_BUSY`](https://vitehub.dev/docs/workspace/diagnostics/workspace_lock_busy) | Another vitehub command is writing vitehub.lock: vitehub.lock.lock exists. |
| [`WORKSPACE_LOCK_INVALID`](https://vitehub.dev/docs/workspace/diagnostics/workspace_lock_invalid) | vitehub.lock has no `version: 1` and `workspaces` object. |

## Operation errors

| Code | What happened |
| --- | --- |
| [`WORKSPACE_FORBIDDEN`](https://vitehub.dev/docs/workspace/diagnostics/workspace_forbidden) | An Agent may not write past an edit lease that a person holds. |
| [`WORKSPACE_HISTORY_FAILED`](https://vitehub.dev/docs/workspace/diagnostics/workspace_history_failed) | The history operation of Workspace "\<workspace\>" failed. |
| [`WORKSPACE_HISTORY_INVALID`](https://vitehub.dev/docs/workspace/diagnostics/workspace_history_invalid) | The commit has no changes. Pass `put` or `delete`. |
| [`WORKSPACE_NOT_FOUND`](https://vitehub.dev/docs/workspace/diagnostics/workspace_not_found) | Workspace "\<workspace\>" has no ref or revision "\<id\>". Run `vitehub workspace refs <workspace>` to list refs. |

## Registry errors

| Code | What happened |
| --- | --- |
| [`WORKSPACE_REGISTRY_LOAD_FAILED`](https://vitehub.dev/docs/workspace/diagnostics/workspace_registry_load_failed) | The module of Workspace "\<workspace\>" did not load: \<reason\> |

## Source errors

| Code | What happened |
| --- | --- |
| [`WORKSPACE_SOURCE_ACCESS_FAILED`](https://vitehub.dev/docs/workspace/diagnostics/workspace_source_access_failed) | Source "\<source\>" of Workspace "\<workspace\>" cannot reach its data with the credentials of the build. The deployed app would fail on its first read. |

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

- [Overview](https://vitehub.dev/raw/docs/workspace.md)
- [Get started](https://vitehub.dev/raw/docs/workspace/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/workspace/configure.md)
- [Server API](https://vitehub.dev/raw/docs/workspace/server-api.md)
- [Agent capability](https://vitehub.dev/raw/docs/workspace/agent-capability.md)
- [Hosts](https://vitehub.dev/raw/docs/workspace/hosts.md)
- [Limits and errors](https://vitehub.dev/raw/docs/workspace/limits-and-errors.md)
- [Workspaces and Sources](https://vitehub.dev/raw/docs/workspace/concepts.md)

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