Diagnostics reference

Every diagnostic Xeer emits carries a stable XE#### code. There are 165 of them, and this page is generated from the same catalogue the compiler and CLI emit from, so it cannot fall behind.

Codes are stable; messages are not. Dispatch on code, read message and span for the location, and treat hint as the platform's own suggested edit.

TypeScript

interface Diagnostic {
  code: string;                 // XE####, stable
  severity: 'error' | 'warning' | 'info';
  message: string;              // human wording, free to change
  file?: string;                // project-relative POSIX path, never absolute
  span?: { line: number; column: number; length?: number };  // 1-based
  hint?: string;                // suggested edit
  primary?: true;               // this broke the generated contract — repair it first
  causedBy?: string;            // a consequence of that code, not an independent error
}

The last two fields are optional and may be absent from an entire envelope; absence means nothing was attributed, not that a diagnostic is independent. A failure that invalidates the generated contract — a defineServer the compiler cannot read statically, a duplicate operation name, an operation result the platform cannot encode — makes every type derived from those operations wrong, so the files that consume the contract fill with XE1205 type errors their authors never caused. Repair the primary: true diagnostics first, ignore the causedBy ones until the primaries are clean, then re-run: whatever still reports is real. Such a run emits its primaries ahead of the rest, so the diagnostic worth reading is also the first one printed.

Every command prints these as JSON with --json; see Building with AI agents. The "Seen in" column lists the commands whose output can carry the code. check diagnostics also appear in build and dev, because both run the same manifest and analysis stages first.

#CLI (XE00xx)

The command itself failed. Not an application defect.

Code	Seen in	Means	Repair
`XE0000`	any	The CLI crashed before it could report a structured result. Written to stderr, so it is the one code that can arrive outside a JSON envelope.	Report it: an internal error is a platform bug, not a project defect. stderr carries the stack.
`XE0001`	any	Unknown or unimplemented command.	Read `xeer --help` and use a documented command.
`XE0002`	any	A CLI option is unknown, lacks its required value, or assigns a value to a boolean flag.	Use an option shown by `xeer --help`; preview deployment is `xeer deploy --environment preview`.

#Manifest (XE10xx)

xeer.app.json is missing, unparseable, or violates the application-source schema — including the database schema, indexes, capabilities, and budgets it declares.

Code	Seen in	Means	Repair
`XE1001`	check, build, dev, test	xeer.app.json was not found in the target directory.	Run `xeer new <directory>`, or point the command at the project root that holds the manifest.
`XE1002`	check, build, dev, test	A manifest value is invalid: bad JSON, a failed schema rule, or an entrypoint that does not exist. Also covers the declared database schema — unknown field types, an index naming a field the table does not declare, reserved field names, and tables declared without the "database" capability — and every capability declaration: an unknown capability name, one declared twice, a config block whose capability is not in `capabilities` (or the reverse), and a declared limit above the platform ceiling.	Read the message: it names the failing manifest path (for example database.tables.notes.indexes.by_owner) and the rule. Correct that one value. A capability and its config block are one declaration in two halves — `"capabilities": ["storage"]` and a `"storage": {}` block — so either add the missing half or remove the present one.
`XE1003`	check, build, dev, test	The manifest carries a property the application-source schema does not define.	Remove the property, or fix its spelling. The manifest is closed: unknown keys are never ignored.

#Manifest paths (XE11xx)

A manifest path does not resolve to a file inside the project root.

Code	Seen in	Means	Repair
`XE1101`	check, build, dev, test	An entrypoint path is absolute or escapes the project root.	Use a forward-slash path relative to xeer.app.json that stays inside the project.

#Module graph and zones (XE12xx)

The client and server graphs are walked separately. Each zone has its own package allowlist, every import must be a static literal resolving inside the project, and shared code lives under src/shared/. Type errors in the reachable graph land here too.

Code	Seen in	Means	Repair
`XE1201`	check, build, dev, test	A source import breaks the zone boundary: it is absolute, leaves the project root, reaches the opposite entrypoint, or pulls a module out of the other zone's graph. A cross-zone import is reported at the import that admitted the module, not at the modules it dragged in — those are correct where they live. A module both graphs reach with no zone-exclusive import anywhere beneath it names no offending side, and is reported on the module itself.	Keep imports relative and inside the project; never import one entrypoint from the other. For a cross-zone import, delete the import the message points at: move code both zones need to src/shared/ and import it from there, or expose the data through a query, mutation, or endpoint and call it from the client. Do not remove the zone imports from the modules it reached.
`XE1202`	check, build, dev, test	A package import violates the zone's import policy structurally: a Node builtin or a native addon (.node) in any zone, a platform subpath the zone does not admit, a renderer-family entrypoint that is test-only, metadata, or unknown to the selected runtime source, or a package family the other zone owns — the renderer (preact, react, react-dom, scheduler) in the server zone. It is not reported for an ordinary npm package in either zone: both admit any declared and installed dependency.	The client zone admits @impetik/xeer/client, @impetik/xeer/client/core, @impetik/xeer/shared, @impetik/xeer/jsx-runtime, @impetik/xeer/jsx-dev-runtime and the platform-managed renderer surface, which is whichever provider client.runtime.provider selects — under preact, preact with its supported entrypoints, with the React-ecosystem specifiers aliased onto preact/compat; under react, react, react-dom and scheduler with their supported entrypoints, and preact refused as the unselected renderer; the server zone admits @impetik/xeer/server, @impetik/xeer/shared. Both zones additionally admit any npm package declared in package.json dependencies and installed. Node builtins and native addons are never importable anywhere: the client runs in a browser and the server runs in workerd, neither of which has them — that is a runtime fact, not an allowlist. Move the code to the zone that owns the import, or use a dependency that targets browsers and workers.
`XE1203`	check, build, dev, test	A dynamic import() specifier is not a string literal.	Use a literal specifier so the module graph stays statically knowable, or a static import.
`XE1204`	check, build, dev, test	A relative source import does not resolve to a file.	Write the specifier without an extension, or with the file's real one: the resolver appends candidate extensions rather than rewriting them, so ./shared/title.js does not find shared/title.ts. Directory imports resolve to index.*.
`XE1205`	check, build, dev, test	TypeScript reported an error in a file reachable from an entrypoint. The message starts with the TS#### code and span points at the exact position.	Fix the type error. Operation input and result types come from the generated contract, so a mismatch between a client call and its server handler surfaces here. A handler whose result the platform cannot encode is reported on the handler: declare result shapes with a `type` alias rather than an `interface`, which TypeScript never gives an implicit index signature.
`XE1206`	check, build, dev, test	A stylesheet is imported outside the client graph.	Import .css only from client modules; the server bundle has no styling stage.
`XE1207`	check, build, dev, test	An import names an npm package that package.json does not declare in "dependencies". It may still resolve through hoisting, which is exactly the accident the rule exists to prevent. Reported in both zones: the message names the zone the import was written in, but the rule is the same one.	Add the package to the application's package.json "dependencies" and install it. Either zone may import any declared and installed npm package; type-only imports may come from devDependencies instead.
`XE1208`	check, build, dev, test	An import names a declared dependency that is not installed: nothing in a reachable node_modules provides it. Reported in both zones.	Run your package manager's install (npm install / pnpm install) so the declared dependency is present on disk, then check again.
`XE1209`	check, build, dev, test	A subresource — an image, a font, or a wasm module — is imported outside the client graph. The declarations that give such an import a type are program-global, so it type-checks in every zone, but only the client bundler has a loader that turns one into a URL.	Import images, fonts, and wasm only from client modules; the server bundle has no asset stage. A server handler that needs the bytes should read them from public/ or receive the URL from the client.
`XE1210`	check, build, dev, test	package.json declares a package the platform provides — the renderer selected by `client.runtime.provider`, or one of the React-family names that resolve to it. The declaration has no effect on what the application bundles: every one of those specifiers is pinned to the platform's copy, for application code and for dependencies alike. A warning rather than an error, so an application that already carries the declaration keeps building.	Remove the package from "dependencies". A library that peer-depends on the renderer is already satisfied by the platform copy, so the declaration buys nothing — and it gives the package manager a second copy to reconcile, which is how an unrelated later install starts failing.
`XE1211`	check, build, dev, test	The renderer a package manager resolves for this project is a different version from the one the platform bundles. The message names both versions and which of them ships. A second copy usually arrives when a package manager hoists an older peer of some dependency to the project root; nothing in the application selected it, and nothing in the application is served by it.	Nothing is required — the artifact contains the platform copy either way. To make the tree agree with the artifact, remove any renderer package from "dependencies" and reinstall. When package.json declares none there is nothing to remove, and the diagnostic's own hint says what to do instead.
`XE1212`	check, build, dev, test	xeer.app.json acknowledges a dependency as untyped that package.json does not declare in dependencies. The acknowledgment describes the type declarations of a package this application never said it uses, so either the declaration is missing or the acknowledgment outlived the dependency it was written for.	Declare the package in package.json "dependencies" if the application imports it, or remove it from "untypedDependencies" in xeer.app.json if it does not.
`XE1213`	check, build, dev, test	xeer.app.json acknowledges a dependency as untyped, but it already resolves to TypeScript declarations — its own, or a separately installed @types companion. The acknowledgment is ignored rather than applied, because generating an ambient declaration for it would not be redundant: an ambient declaration overrides module resolution, so it would replace real declarations with `any` and a call with the wrong argument types would compile clean. The real declarations still apply.	Remove the package from "untypedDependencies" in xeer.app.json. Its own declarations are what the application is being checked against either way.
`XE1214`	check, build, dev, test	xeer.app.json acknowledges a dependency as shipping no TypeScript declarations, so it and every subpath under it are typed as `any`. Informational, and emitted on every check for as long as the acknowledgment stands: the acknowledgment is a deliberate hole in type safety, and one that is never reported is one nobody removes.	Nothing is required. If declarations are published — conventionally at @types/, with a scope flattened as @types/scope__name — install them and remove the acknowledgment.

#Operations (XE13xx)

The default defineServer({...}) export is read statically, so operation and endpoint registration must be a literal object with valid, unambiguous names.

Code	Seen in	Means	Repair
`XE1300`	check, build, dev, test	The default server export is not a statically inspectable defineServer({...}) call, or an operation group is not a literal object.	Export `default defineServer({ queries: {...}, mutations: {...}, endpoints: {...} })` with literal object members: no spreads, shorthand, computed keys, or wrappers.
`XE1301`	check, build, dev, test	Two operations in the same group share a name.	Rename one of them, or delete the duplicate registration if it was a copy-paste.
`XE1302`	check, build, dev, test	An endpoint key is not `METHOD /api/path`.	Use an uppercase HTTP method, one space, and a literal /api path; dynamic segments are :name.
`XE1303`	check, build, dev, test	A query or mutation name does not match the operation-name grammar: two or more dot-separated segments, each starting with a lowercase letter and continuing with lowercase letters, digits, `_`, or `-`.	Write the name as `namespace.name` with no uppercase letter anywhere — uppercase is the restriction authors do not expect, so `posts.bySlug` is refused even though it is namespaced. Separate words with `_` or `-` instead: notes.list, notes.list_pinned, notes.by-slug, and notes.pinned.v2 are all accepted. Formally `^[a-z][a-z0-9_-]\.[a-z][a-z0-9_.-]$`.
`XE1304`	check, build, dev, test	Two endpoints reduce to the same route shape, so dispatch would be ambiguous.	Change the method or a static path segment. Parameter names do not distinguish routes: GET /api/notes/:id and GET /api/notes/:slug are the same route.

#Budgets and assets (XE14xx)

A module or public asset breaks a v0 size limit, collides with generated output, or claims a platform-reserved path.

Code	Seen in	Means	Repair
`XE1401`	build, dev, test	A compiled module (10 MiB) or an asset (25 MiB) exceeds the v0 limit.	Shrink the module or asset. There is no flag that raises a v0 limit.
`XE1402`	build, dev, test	A file in public/ collides with generated output.	Rename the public file; the platform generates the application document at /index.html.
`XE1403`	build, dev, test	A file in public/ claims a platform-reserved path.	Move it: /_xeer/, /__xeer/ and /_xa/* belong to the platform.
`XE1404`	build, dev, test	The manifest declares a favicon the project does not ship in public/.	Add the file under public/, or drop app.favicon. Emitting the reference anyway would put a link that 404s into every document the application serves.
`XE1405`	build, dev, test	The minified client JavaScript bundle exceeds its byte budget — the platform's 1024 KiB default, or the manifest's `budgets.clientBundleBytes` when declared. The message attributes bytes to the packages that contributed them.	Read the attribution in the message and remove or replace the heaviest dependency, or raise `budgets.clientBundleBytes` (bounded by the 10 MiB module ceiling) if the size is intended.
`XE1406`	build, dev, test	The application's own share of the minified client JavaScript bundle exceeds the fixed 400 KiB advisory tier — the bundle minus the platform-selected renderer, which an application neither declares nor can remove. The build still succeeds; this is a warning with per-package byte attribution. The error tier (XE1405) is measured over the whole bundle instead.	Nothing is required. If the growth is unintended, the attribution in the message names the packages to reconsider before the error tier is reached.

#Bundling (XE15xx)

The client or server bundle failed after analysis passed.

Code	Seen in	Means	Repair
`XE1501`	build, dev, test	Bundling failed after the module graph and types were accepted.	Read the bundler message in `message`. It usually names a syntax construct the target does not support, rather than a Xeer rule.
`XE1502`	build, dev, test	A bundled dependency imports a Node builtin, so the bundle cannot run where its zone runs — a browser for the client zone, workerd for the server zone. The message names the zone, the dependency and the builtin; the offending import sits inside the package, not in application code. The diagnostic is located at the application import that admitted the package into that zone's graph.	Use a package targeting browsers and workers, or the package's browser/worker entrypoint. Neither zone has Node builtins to offer, so the platform refuses the bundle rather than shipping one that throws at load time. This is a property of the dependency chain and so is found at build, not at check.
`XE1503`	check, build, dev, test	The client bundle would contain a renderer it must not: a second physical copy of the one the application selected, or the one it did not. Bare renderer imports are pinned to the platform anchor, so a second copy means a path-based escape — a relative or absolute import reaching into some node_modules copy of the renderer. The unselected renderer is installed by the platform whichever provider an application chooses, so only this rule keeps it out of the bundle.	Import the renderer by its bare specifier (preact, preact/hooks, react, …) so the platform pins it to one instance, and import only the renderer client.runtime.provider selects. Two copies of one renderer means two options singletons — hooks and components silently stop sharing state; two different renderers means two reconcilers rendering into one tree.

#Development loop (XE16xx)

A watch rebuild failed. The last-good preview stays active and is rolled back to; these codes arrive as compile.diagnostic events, never as a dead server.

Code	Seen in	Means	Repair
`XE1602`	dev	A watch rebuild failed. The previously accepted generation is still serving.	Fix the edit named by `file`. The next quiet-window rebuild promotes automatically; no restart.
`XE1603`	dev	A rebuilt candidate compiled but failed to take over — usually a manifest or schema change the running state cannot accept — and the last-good generation was restored.	Fix the manifest or schema change. To adopt an incompatible schema locally, stop dev and run `xeer state reset . --state dev --confirm <application>`.
`XE1604`	dev	The manifest could not be watched for changes, so edits to it will not rebuild the preview. Everything already serving keeps serving.	On Linux this is normally an exhausted inotify allowance: raise `fs.inotify.max_user_watches` and `fs.inotify.max_user_instances`. Restart `xeer dev` afterwards.
`XE1605`	dev	A rebuild changed `client.runtime` — the UI provider — under a running dev server. The preview keeps serving the renderer it started with rather than serving the new manifest through the old one.	Stop and restart `xeer dev`. The dev server resolves its JSX runtime, its renderer aliases, and its Fast Refresh transform once, at startup; `xeer build` and `xeer preview` need no restart.

#Artifact preview (XE17xx)

xeer preview verifies the content-addressed artifact and its blobs before booting. These codes mean the build output is missing, malformed, or does not match its own identity.

Code	Seen in	Means	Repair
`XE1700`	build, preview, test, deploy, state	No verifiable build artifact was found for preview.	Run `xeer build` first; preview never compiles.
`XE1701`	build, preview, test, deploy, state	The artifact, its latest pointer, or its server source map is malformed.	Rebuild with `xeer build`. Do not hand-edit anything under .xeer/build/. If a fresh build reports this itself, it is a compiler defect: report it with the diagnostic.
`XE1702`	build, preview, test, deploy, state	The artifact does not match its own content-addressed identity or schema identity.	Rebuild. A mismatch means the output was mutated after it was written.
`XE1703`	build, preview, test, deploy, state	An artifact blob is missing, the wrong size, or hashes differently than its receipt.	Rebuild. The build output is incomplete or corrupted.
`XE1704`	preview	The artifact preview server failed to start or crashed.	Read `message`. Re-run `xeer build`, then preview again.
`XE1705`	build, preview, test, deploy	The latest build is stale: source files recorded in the artifact have changed on disk since it was made, so running it would run code the project no longer has. Compared by content hash, never by timestamp. `message` names the changed files.	Run `xeer build`. `xeer deploy` and `xeer test` build for you, so this means the build is older than the edit — most often `xeer preview`, which runs the last verified artifact and never compiles.

#Local state and state transfer (XE18xx)

Local dev/preview/test state is leased per project and mode, destructive resets are confirmed by exact application name, and xeer export/xeer import move it as a versioned xeer.state-export.v0 document that must fit the schema currently in force.

Code	Seen in	Means	Repair
`XE1801`	state	A state command was invoked without a valid --state selector.	Pass `--state dev`, `--state preview`, or `--state test`. The three modes never share a root.
`XE1810`	state	A destructive state command was invoked without --confirm.	Pass `--confirm <application>` using the manifest `name` exactly.
`XE1811`	state	The --confirm value does not match the application name.	Use the manifest `name` verbatim; the guard is exact-match by design.
`XE1812`	dev, preview, test, state	The local state lease for that project and mode could not be acquired, or is held by a live process. Two concurrent `xeer test` runs in one project report this rather than racing.	Stop the other `xeer dev`/`xeer preview`/`xeer test` for this project and retry.
`XE1813`	dev, preview, test, state	The resolved state directory escapes its Xeer-owned project or local-data container, or traverses a link.	Remove the link under .xeer/ (or the Xeer/state local-data directory on an overlong Windows path) and retry.
`XE1814`	dev, preview, test, state	A local state operation failed for an underlying filesystem reason.	Read `message`. Usually permissions or a partially removed .xeer/ directory.
`XE1820`	export, import	No `xeer dev`/`xeer preview` server owns that mode's state in that directory, or it has not published its address yet. Local state lives in a Durable Object, so only the running runtime can read or write it.	Start `xeer dev` (or `xeer preview`) in that directory and re-run, or pass a deployed application name, appId, or URL instead.
`XE1840`	db	No `xeer dev`/`xeer preview` server is running for that directory, so its database cannot be reached. The database lives inside a Durable Object; the running runtime is the only thing that can read it consistently.	Start `xeer dev` (or `xeer preview`) in that directory and re-run.
`XE1841`	db	The running server published no admin session secret, so its database surface is not reachable. The secret is minted per run and shared through the state lease.	Restart the server with a build that publishes one; a server older than this CLI does not.
`XE1842`	db	The server answered the database request with a protocol this CLI does not know.	The CLI and the running server are different versions. Restart the server from this checkout.
`XE1821`	export, import	The export file could not be read or written.	Read `message`: usually a missing path or permissions. `--out` creates parent directories.
`XE1822`	export, import	The document is not a usable xeer.state-export.v0 export: wrong protocol, or it contradicts itself (counts, schema, or an encoded value).	Import the unmodified file `xeer export --out` produced. `detail.code` names the exact defect.
`XE1823`	import	`xeer import` was pointed at a deployed application. It writes local dev and preview state only; a deployed import needs a write-scoped grant and a pre-import snapshot.	Import into `xeer dev`/`xeer preview` state (`--state dev`), verify there, and `xeer deploy`.
`XE1824`	export, import	The runtime refused the transfer. `detail.code` is the reason: state_import_schema_mismatch, state_import_application_mismatch, state_import_record_invalid, or state_export_too_large.	For a schema mismatch, `detail.expected` and `detail.found` carry both schema identities: check out the schema the export came from, import there, and let the compatible-change path carry the data forward, or re-export from the current schema. There is no forced import.
`XE1825`	export, import	The command was invoked without a usable target, without the export file, or with a --state value other than dev or preview.	Pass `<preview-url\|app>` or `--state dev\|preview [directory]`; `xeer import` also needs the file.

#Tests (XE19xx)

xeer test builds the project, type-checks tests/**/*.test.ts against the generated contract, and runs each test against a fresh isolated state. A failure carries the standard Diagnostic fields plus kind, matcher, expected, and actual, so the same parser handles it.

Code	Seen in	Means	Repair
`XE1900`	test	xeer test found no test files.	Create tests/.test.ts importing test, as, and expect from @impetik/xeer/test. `xeer new` scaffolds a passing suite to copy.
`XE1901`	test	A test file could not be compiled.	Read `message`: it is the bundler error for that file. Test files may import @impetik/xeer/test, @impetik/xeer/shared, and project-relative modules.
`XE1902`	test	The test runtime failed to start.	Not a test failure. Run `xeer build` and `xeer doctor` — the artifact or the local workerd toolchain is the problem.
`XE1903`	test	A test file threw while loading, so none of its tests ran. Other files still run.	Move work out of module scope and into a test body; only test registration belongs at the top level.
`XE1904`	test	An assertion failed. The failure carries `matcher`, `expected`, `actual`, and the project-relative test location.	Decide which side is wrong. If the application is wrong, fix it and re-run; if the expectation is wrong, fix the test. Never delete the assertion to go green.
`XE1905`	test	A test threw, including a call that was refused when the test did not expect it. `operation` names the persona, operation, status, and runtime error code.	When the refusal is the point, wrap the call in expectFailure(). A refused workspace-scoped call usually means the persona's declared membership does not contain the workspace the operation names: pass it with as({ name, workspaceIds }).
`XE1906`	test	A test exceeded its 20 second budget. The remaining tests still run.	Remove the wait: tests run against a local runtime, so a timeout means an unresolved promise or an operation that never returns, not a slow machine.

#Inspector (XE20xx)

An inspector request failed. Locally the target is a preview URL; for a deployed app the request is routed through the control plane and requires builder ownership.

Code	Seen in	Means	Repair
`XE2001`	inspect, state	An inspector command was invoked without a target, or with a project directory in which no `xeer dev` or `xeer preview` server is running — or in which both are, so the directory does not name one of them.	Pass a project directory (`.`) to read the local server running for it, the URL from the dev/preview `preview.ready` event, or a deployed application name, appId, or URL.
`XE2002`	inspect, state	The inspector request itself failed: a local dev/preview inspector that answered a non-2xx status or no JSON, or a control plane that refused the proxied read, in which case the read never reached the application. An application that refused the read is XE2004.	Confirm the preview is still running and the URL matches the current `preview.ready` event. For a deployed read, `message` carries the control plane's own refusal.
`XE2003`	inspect, state	No deployed application matched the inspector target for the signed-in builder.	Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with `xeer auth status` that you are signed in as its owner.
`XE2004`	inspect, state, export	The deployed application refused the read itself, and the control plane forwarded its answer. The application's own runtime code, its errorId, and the cause are in `message`, and in `detail` as `code`, `errorId`, and `appId`.	Dispatch on `detail.code`, not on the wording. `state_bootstrap_failed` means the application state never bootstrapped, so the read never ran: fix the cause named in `message` and redeploy. `state_unavailable` means the read never reached the state object at all — most often a brand-new application whose state namespace is not dispatchable yet — so there is nothing to fix: wait out the advertised retry and read again. Quote `detail.errorId` when correlating with the Worker's console output.

#Scaffold (XE30xx)

xeer new could not create the project.

Code	Seen in	Means	Repair
`XE3001`	new	xeer new could not scaffold the project — most often a non-empty target directory.	Choose an empty or non-existent directory.
`XE3002`	new	`--template` named neither a bundled starter nor an exact id in the reachable catalog.	Check the exact catalog id, use a bundled starter, or omit --template for the default. A framework scaffold is selected with `--framework`.
`XE3003`	new	`--ui` named a UI provider that does not exist. Refused before the target directory is read, so nothing was written.	Use preact or react, or omit --ui for the default (preact). The choice is orthogonal to --template for every Xeer application template: each scaffolds on either provider from the same client sources.
`XE3004`	new	`--ui` was passed with `--framework`, and a framework renders through its own toolchain rather than through a Xeer UI provider. Refused before the target directory is read, so nothing was written.	Drop --ui. `--framework sveltekit` owns its renderer: it writes no client.runtime.provider to select, and no value of --ui would change a file it writes.
`XE3005`	new	`--template` and `--framework` were passed together. They are two exclusive axes: one writes a Xeer application, the other a project Xeer runs rather than compiles. Refused before the target directory is read, so nothing was written.	Pass exactly one. Keep --template for a bundled Xeer application starter, or keep --framework to scaffold a fresh framework project.
`XE3006`	new	`--framework` named a framework Xeer cannot scaffold. Refused before the target directory is read, so nothing was written.	Use one of the names the message lists, or omit --framework to scaffold a Xeer application. To adopt a framework project that already exists, run `xeer init` in it instead.
`XE3007`	new	xeer new could not reach or read the template catalog.	Check the network connection and repeat the command.
`XE3008`	new	The reachable template catalog is invalid for installation.	Wait for the catalog publisher to be repaired, then repeat the command.
`XE3009`	new	xeer new could not download the selected template archive.	Check the network connection and repeat the command.
`XE3010`	new	The downloaded template archive does not match the catalog SHA-256.	Do not use the bytes. Repeat later or report the template artifact.
`XE3011`	new	The downloaded template archive contains unsafe or unsupported content.	Report the template artifact and choose another template.
`XE3012`	new	The extracted project root does not match the project metadata declared by the catalog.	Report the template artifact and choose another template.
`XE3013`	new	`--ui` was passed with a catalog template, which owns its project kind and renderer.	Drop --ui and install the catalog template unchanged.

#Agent setup (XE31xx)

xeer agent setup found missing, stale, invalid, or user-owned adapter files.

Code	Seen in	Means	Repair
`XE3101`	agent	Agent setup check found one or more generated files missing or stale. No files were written.	Run `xeer agent setup`, then repeat `xeer agent setup --check --json`.
`XE3102`	agent	Agent setup found a path owned by the user or another tool. The entire write was refused.	Move, rename, or deliberately remove the conflicting path; setup never overwrites an unowned file.
`XE3103`	agent	`--target` named an agent adapter that Xeer does not support.	Use auto, agents, claude, codex, cursor, vscode, or mcp.

#Existing-project initialization (XE32xx)

xeer init could not identify or safely initialize an existing framework project.

Code	Seen in	Means	Repair
`XE3201`	init	xeer init did not find an existing SvelteKit package at the selected directory.	Run xeer init from the SvelteKit package directory, or pass that directory explicitly.
`XE3202`	init	xeer init found an existing xeer.config.json that it does not own.	Keep and configure the existing file deliberately; xeer init never overwrites an unowned file.
`XE3203`	init	xeer init could not read the existing package.json.	Repair package.json, then run xeer init again. No files were written.
`XE3204`	check, dev, build, test, deploy	A framework package script required by Xeer is missing, unavailable, or failed. A failing check reports one diagnostic per file it could locate, with `file` and `span`.	Run the command named in the diagnostic, repair its output, and repeat the Xeer command.
`XE3205`	check, dev, build, test, deploy, doctor	xeer.config.json or its adjacent package.json is invalid.	Repair the file named by the diagnostic, then repeat the Xeer command.
`XE3206`	init	Wrangler could not configure the existing framework project for Cloudflare Workers.	Repair the Wrangler setup failure, or run wrangler setup manually, then repeat xeer init.
`XE3207`	build, deploy, test	The framework build failed, left its previous output in place, or produced something the platform will not deploy: no Cloudflare Worker at the path the Wrangler configuration names, or a module, asset, or total payload over the v0 size limits.	Read the message: it names the paths that were checked, or the limit that was exceeded. Repair the project build, then repeat the Xeer build or deploy.
`XE3208`	preview, inspect, state, agent	The command reads a Xeer application contract that a framework project does not have. A project with xeer.config.json owns its own routing, rendering, and datastore, so there is no Xeer manifest, artifact preview, state, or log ring to read.	Use the framework equivalent the hint names — `xeer dev` for a running server, `xeer check` for the project's own diagnostics — or run the command against a Xeer application (xeer.app.json). Never scaffold a new project over an initialized one.

#Environment (XE40xx)

xeer doctor found a broken toolchain or generated-file state. The failing check id and details are in result.checks.

Code	Seen in	Means	Repair
`XE4001`	doctor	A doctor check failed. `hint` carries the check details as JSON, and result.checks lists every check with its id and status.	Fix the environment problem the failing check names. Doctor never edits the project.

#Builder authentication (XE50xx)

Builder sign-in against the control plane. Sign-in is a human step; an agent reads these codes and asks for it.

Code	Seen in	Means	Repair
`XE5000`	auth	An auth subcommand was invoked with wrong arguments.	Use `xeer auth <login\|status\|logout\|as\|clear>`; `auth as` takes alice, bob, or carol.
`XE5001`	auth, deploy	The --control-url value is not an exact HTTP(S) origin, or is plain HTTP off localhost.	Pass an origin such as https://control.example.com with no path.
`XE5002`	auth, deploy	No valid builder credential is stored.	A human must run `xeer auth login` and approve the shown code. An agent cannot complete sign-in.
`XE5003`	auth, deploy	XEER_SERVICE_TOKEN is set to something that is not a service token, so no command that authenticates can present a credential. The value is never echoed; it is a live secret.	Set it to `xst_` followed by 43 characters — `xeer token create --name <label>` issues one — or unset it to fall back to the credential `xeer auth login` stored on this machine.
`XE5004`	auth	The control plane returned a response the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5005`	auth	The device authorization expired before sign-in completed.	Run `xeer auth login` again and approve promptly.
`XE5008`	auth, deploy	The stored CLI credential file is unreadable or invalid.	Run `xeer auth logout` and sign in again.
`XE5009`	auth	An auth command failed without a more specific code.	Read `message`; it is the underlying error verbatim.

#Deployment, project identity, environment variables, and service tokens (XE51xx)

The deployment itself; the checked-in xeer.project.json appId that decides which hosted app a checkout deploys to, where the repair is always xeer link rather than a new appId; the per-project encrypted environment store behind xeer env; and the deployment history behind xeer deployments; plus the hidden service-token lifecycle behind xeer token.

Code	Seen in	Means	Repair
`XE5101`	deploy	The deployment Worker module could not be constructed from the artifact.	Re-run `xeer build` and inspect the artifact; the build output is incomplete.
`XE5102`	deploy	The control plane rejected the deployment or answered without a usable JSON envelope.	Read `message`: it carries the control-plane error. Check sign-in and that the project name is claimable.
`XE5103`	deploy	The deployment was accepted but the deployed runtime never became ready.	The upload succeeded; the runtime did not. Retry, then report it — the artifact is already recorded.
`XE5104`	deploy	The deployment serves assets but authenticated requests fail.	A platform identity problem, not an application one. Report it with the diagnostic message.
`XE5105`	deploy	The --environment value is not a deployable scope.	Pass prod, production, or preview. `dev` is a local-only scope that `xeer env pull` writes to a gitignored file; no deployment ever injects it.
`XE5106`	deploy, promote, rollback	A capability the manifest declares could not be provisioned. Either the control plane could not create or adopt the backing resource (a per-app R2 bucket for "storage"), it is not configured to provision at all, or it does not support that capability name. Nothing was activated: the previous version is still serving.	Retry the deployment — provisioning is adopt-or-create, so a half-finished attempt heals on the next one. A capability the control plane does not recognise is not retryable: remove it from `capabilities` in xeer.app.json, or deploy against a control plane that supports it. `message` carries the control plane's own reason.
`XE5107`	deploy	The build `xeer deploy` runs before uploading failed, so nothing was deployed and the previously deployed version is still serving. The compiler's own diagnostics follow this one in `diagnostics`.	Repair the diagnostics that follow — they are exactly what `xeer build` reports — and deploy again. Deploy never falls back to the last successful build.
`XE5109`	deploy	Deployment failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5111`	deploy	The appId declared in xeer.project.json is owned by a different builder, so the control plane refused the deployment.	Run `xeer link --new` to fork this checkout into a new app you own, or `xeer link` to attach it to one of yours. A clone of someone else's project cannot silently take over their app.
`XE5112`	deploy	The builder is at their apps-per-builder quota, so the control plane refused to create the app this deployment would have claimed.	This quota is a standing cap and does not lift on its own. Run `xeer link` to deploy into an app you already own, or ask the Xeer team to raise it. `message` states the quota and your usage.
`XE5113`	deploy	The builder has spent their hourly or daily deploy quota.	Retry after the reset `message` states — it is the exact moment a slot frees, not a fixed backoff. Failed deployments count toward the quota, so a fix-and-retry loop spends it too.
`XE5120`	deploy, link, dev, preview, test, doctor	xeer.project.json exists but is unusable: not JSON, not an object, the wrong `format`, or without a valid `appId`.	Run `xeer link --app <appId>` to rewrite it, or `xeer link --new` to mint a fresh identity. A present-but-broken file is never repaired by guessing, because that would fork the app.
`XE5121`	deploy, link, dev, preview, test, doctor	The checked-in xeer.project.json and the local .xeer/project.json cache name different appIds.	The checked-in file wins. `xeer link --app <declared appId>` re-points the cache, or `xeer link --new` deliberately forks this checkout.
`XE5122`	link, deploy	An appId is malformed, or `xeer link` was given both --app and --new.	Run `xeer link` with no flags to list the appIds you own, then pass exactly one of --app or --new.
`XE5123`	link	The signed-in builder does not own a project with that appId.	Run `xeer link` to list your projects, or `xeer link --new` to create a new app for this checkout.
`XE5124`	link	The control plane returned an invalid project or project list.	Retry; if it persists the control plane is unreachable or misconfigured. Not a project defect.
`XE5129`	link	xeer link failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5130`	env	An `xeer env` invocation is wrong: an unknown --environment, a missing name or value, or no usable xeer.app.json in the target directory.	Read `message` and the usage it quotes. --environment takes prod, preview, or dev, and the command must run inside a Xeer project.
`XE5131`	env	The control plane rejected the environment-variable request.	Read `message`: it carries the control-plane error and hint. Check sign-in and that you own the project.
`XE5132`	env	The control plane returned an environment payload the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5133`	env	A closed-beta quota refused the environment-variable request: `xeer env set` claims the project on first use, so it is capped by the same apps-per-builder quota as `xeer deploy`.	Set the value on an app you already own — `xeer link` lists them — or ask the Xeer team to raise the quota. `message` states the quota, your usage, and any reset.
`XE5134`	dev, preview, test	A file exists at `.xeer/env.<environment>.local.json` but could not be used in full: it is not a `xeer.env-local.v0` document, it could not be read, or some of its entries have names or values a local run cannot load — so `ctx.env` is missing them.	Read `message`: it names the file and the exact problem — the shape to write is {"format": "xeer.env-local.v0", "values": {"NAME": "value"}} with UPPER_SNAKE_CASE names and string values. `xeer env pull` writes the file correctly.
`XE5139`	env	xeer env failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5140`	deployments	An `xeer deployments` invocation is wrong: an unusable --limit, or a directory that declares no app identity.	Read `message`. --limit takes a positive integer up to 200. In a directory with no appId, run `xeer deploy` or `xeer link` first, or name the app: `xeer deployments <app>`.
`XE5141`	deployments	The control plane rejected the deployment-history request.	Read `message`: it carries the control-plane error and hint. Check sign-in and that you own the app.
`XE5142`	deployments	The control plane returned a deployment listing the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5143`	deployments	No app matched the reference for the signed-in builder.	Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with `xeer auth status` that you are signed in as its owner.
`XE5149`	deployments	xeer deployments failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5160`	rollback	An `xeer rollback` invocation is wrong: a missing or malformed artifact id, an unknown --environment, or a directory that declares no app identity.	An artifact id is `sha256:` followed by 64 hex characters — copy it from the ARTIFACT column of `xeer deployments <app>`. --environment takes prod or preview; `dev` is never deployed.
`XE5161`	rollback	The control plane refused the rollback.	Read `message` and `hint`: they carry the control-plane error verbatim. A rollback is a deployment, so it can also be refused by the deploy quota.
`XE5162`	rollback	The control plane returned a rollback result the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5163`	rollback	No app matched the reference for the signed-in builder, or it has already been deleted.	Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with `xeer auth status` that you are signed in as its owner.
`XE5164`	rollback	This application has no completed deployment of that artifact — it belongs to another project, was never deployed here, or its deployment failed.	Run `xeer deployments <app>` and roll back to an artifact listed there. Only a deployment that completed can be rolled back to.
`XE5169`	rollback	xeer rollback failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5170`	promote	The --from-artifact value is not an artifact id.	An artifact id is `sha256:` followed by 64 hex characters — copy it from the ARTIFACT column of `xeer deployments <app>`. Omit the flag to promote whatever preview is currently serving.
`XE5171`	promote	The control plane refused the promotion.	Read `message` and `hint`: they carry the control-plane error verbatim. A promotion is a production deployment, so it can also be refused by the deploy quota.
`XE5172`	promote	The control plane returned a promotion result the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5173`	promote	No app matched the reference for the signed-in builder, or it has already been deleted.	Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with `xeer auth status` that you are signed in as its owner.
`XE5174`	promote	This application has no completed deployment of that artifact — it belongs to another project, was never deployed here, or its deployment failed.	Run `xeer deployments <app>` and promote an artifact listed there. Only a deployment that completed can be promoted.
`XE5175`	promote	The application has no completed preview deployment, so there is nothing to promote.	Run `xeer deploy --environment preview` to put a version on the preview origin first, or name the version explicitly with `--from-artifact sha256:…`.
`XE5176`	promote	The --receipt value is not a complete review receipt id.	Run `xeer test`, deploy the unchanged project with `--environment preview`, and copy the complete `review_…` id printed by that deployment.
`XE5177`	promote	--receipt and --from-artifact were supplied together.	Use --receipt for the reviewed path, or --from-artifact for the separate direct human override.
`XE5179`	promote	xeer promote failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5150`	disable, enable, delete	A lifecycle invocation is wrong: `xeer delete` without --confirm, or a directory that declares no app identity.	Deleting an application is permanent, so it requires its exact name: `xeer delete <app> --confirm <app>`. In a directory with no appId, name the app instead of relying on the directory.
`XE5151`	disable, enable, delete	The control plane refused the lifecycle change — most often because --confirm does not match the application name, or because it cannot delete the deployed Worker.	Read `message` and `hint`: they carry the control-plane error verbatim. A confirmation must equal the name in xeer.app.json exactly.
`XE5152`	disable, enable, delete	The control plane returned a lifecycle result the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5153`	disable, enable, delete	No app matched the reference for the signed-in builder, or it has already been deleted.	Pass the application name from xeer.app.json, its appId, or its deployed URL, and confirm with `xeer auth status` that you are signed in as its owner. A deleted app never resolves again.
`XE5159`	disable, enable, delete	A lifecycle command failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5180`	token	An `xeer token` invocation is wrong: an unknown action, a missing or unusable --name, a token id that is not an `xstid_` value, or no interactively signed-in builder.	Issuing a service token requires `xeer auth login` first — the browser approval is the root of every credential an account holds, so a service token cannot mint another. Take ids from `xeer token ls`; the id is the `xstid_` value, never the secret.
`XE5181`	token	The control plane refused the service-token request.	Read `message` and `hint`: they carry the control-plane error verbatim. A service token cannot issue another one, and a disabled builder is refused every credential they hold.
`XE5182`	token	The control plane returned a service-token response the CLI will not trust.	Retry; if it persists the control plane is misconfigured or unreachable. Not a project defect.
`XE5189`	token	xeer token failed without a more specific code.	Read `message`; it is the underlying error verbatim.
`XE5190`	domains	An `xeer domains` invocation has a missing or invalid hostname or subcommand.	Use `xeer domains add\|ls\|status\|remove`. A hostname is fully qualified ASCII without a scheme, port, path, or wildcard, for example `app.example.com`.
`XE5191`	domains	The control plane refused a custom-domain request.	Read `message` and `hint`; they carry the owner-scoped control-plane refusal.
`XE5192`	domains	The control plane returned a domains payload the CLI will not trust.	Retry; if it persists, the control plane and CLI versions are incompatible or the service is misconfigured.
`XE5193`	domains	No application or attached domain matched the owner-scoped reference.	Check the application reference and hostname, then confirm `xeer auth status` shows its owner.
`XE5194`	domains	The hostname is unavailable, reserved, at the user quota, or awaiting earlier cleanup.	Read `message` and `hint`. Remove an unused hostname, finish cleanup, or choose a hostname you control.
`XE5195`	domains	The application has no successful production deployment.	Run `xeer deploy` first. A custom hostname is never attached to an application with no production Worker.
`XE5196`	domains	Cloudflare for SaaS is unavailable or rejected the provider operation.	Retry. If it persists, the operator must check the SaaS zone, fallback origin, runtime token, and provider status.
`XE5197`	domains	Routing is detached, but Cloudflare hostname or certificate cleanup remains pending.	Run the same `xeer domains remove` command again. Reattachment stays blocked until cleanup is confirmed.
`XE5199`	domains	xeer domains failed without a more specific code.	Read `message`; it is the underlying error verbatim.