Skip to content

Error code reference

Every error WebCortex reports carries a stable code. A code keeps its meaning once released, so clients, tests and coding agents can branch on WC402 rather than on a message's wording. The table lives in the Rust core (crates/webcortex-core/src/errors.rs); this page lists the same entries. webcortex explain CODE prints one from the command line, and the built-in MCP tool webcortex_explain answers the same question for an agent.

Where a code appears: the code and hint fields of an HTTP error body (and the x-webcortex-error response header), code/hint on an agent run that did not complete and code on its failed steps, structuredContent.error of an MCP tool error, the errors.recent ring of /_webcortex/status, webcortex doctor checks, and CLI failures (error[WC101]: …).

One exception: HTTP/1 protocol errors. A request that does not parse as HTTP/1 at all is answered by hyper, the HTTP library under WebCortex, before WebCortex sees it: a malformed request line or header line (400 Bad Request), a header section over hyper's limit (431 Request Header Fields Too Large) and a request target over its limit (414 URI Too Long). These responses have an empty body, no code, no x-webcortex-error, no x-request-id and none of the security headers, and the connection is closed. hyper offers no hook for the body of its own error responses, so this is a known limit rather than a bug; nothing about the request reached the app, and a client that sends well-formed HTTP never meets it. (Found by the 2.9.0 fuzzing; see SECURITY.md, "Review — 2.9.1".)

Internal faults (WC0xx)

WC001 — Internal error

internal · HTTP 500

Something failed inside the server. The server log has the full error under this response's x-request-id; set WEBCORTEX_DEBUG_ERRORS=1 locally to return Python tracebacks.

WC002 — Python handler raised

internal · HTTP 500

An unhandled exception escaped a Python handler; its traceback is in the server log. Raise webcortex.HTTPError(status, message) for failures the caller should see.

WC003 — Behaviour failed

internal · HTTP 500

A behaviour raised an exception; its traceback is in the server log. Use ctx.halt(reason) to stop a behaviour on purpose.

WC004 — Template failed to render

internal · HTTP 500

A page template is missing or raised while rendering; check the template name and the data the page binds.

Configuration and environment (WC1xx)

WC101 — Invalid application

config

The app's declarations do not validate. The message names the declaration; fix it in api.py and run webcortex check.

WC102 — App failed to load

config

Importing the app module raised, or it does not define app. Run python api.py to see the traceback, or pass module:attr.

WC103 — Core extension mismatch

config

The compiled extension (webcortex._core) is missing or from a different version than the Python package. Reinstall the wheel, or run maturin develop in a working copy.

WC104 — Port already in use

config

Another process is listening on the app's port. Stop it, or choose another with --port or WEBCORTEX_PORT.

WC105 — No database configured

config · HTTP 500

A route needs SQL but WebCortex(...) was given no database=. Pass database="sqlite://./app.db" or set WEBCORTEX_DATABASE_URL.

WC106 — Environment variable not set

config

A declaration names an environment variable that is unset (an API key, a bearer token, a provider key). Export it or add it to .env; values are never printed.

WC107 — Path does not exist

config

A configured directory or database path does not exist. Create it or correct the path.

WC108 — Running app not reachable

config

Nothing answered at the app's address. Start it with webcortex dev, or point the command at it with --url or WEBCORTEX_HOST/WEBCORTEX_PORT.

Routing, HTTP and request input (WC2xx)

WC200 — Request failed

http

The handler answered with an error status and no more specific code. Read the message; a handler can raise HTTPError(status, message, code=..., hint=...) to say more.

WC201 — No such route

http · HTTP 404

No route matches this path. webcortex check lists every route, and GET /_webcortex/routes lists them on a running app.

WC202 — Method not allowed

http · HTTP 405

The path exists but not for this method; the allow header lists the methods it takes.

WC203 — Request timed out

http · HTTP 504

The handler ran past request_timeout (or agent_timeout for agents, behaviours and flows). Raise the limit on WebCortex(...) or make the handler faster.

WC204 — Request body too large

http · HTTP 413

The body is over the 32 MB limit. Send large files to a static or device ingest route in pieces, or reference them by URL.

WC205 — Bad request

http · HTTP 400

The request could not be used as sent: check the JSON body and parameter types against the route's schema in /_webcortex/openapi.json.

WC206 — Missing or invalid parameter

http · HTTP 422

A required parameter was absent or could not be read. Send every required field named in the route's input schema (path, query string or JSON body).

WC207 — Not found

http · HTTP 404

The route exists but the thing it looks up does not: check the id or key you sent.

WC208 — Tool arguments address another route

http · HTTP 400

A path argument would have routed this tool call to a different route. Pass a plain value for the path parameter, not a path.

WC209 — Invalid path parameter

http · HTTP 400

A path parameter contained a slash, '..', or a control character. Path parameters are single segments.

WC210 — Upstream failed

http · HTTP 502

A proxied upstream or a pulled camera did not answer properly. Check that it is reachable from the server and that its bearer_env is set.

WC211 — Database rejected the query

http · HTTP 400

SQLite refused the statement or its values (a constraint, a type). The message is SQLite's; check the values you sent.

WC212 — No such control endpoint

http · HTTP 404

That path is not part of the control plane. GET /_webcortex/health, /status, /routes, /tools, /usage and /audit are the common ones.

WC213 — WebSocket required

http · HTTP 426

This route is a WebSocket. Connect with Upgrade: websocket (webcortex.client.WebSocket or DeviceConnection).

WC214 — Conflict

http · HTTP 409

The request conflicts with the current state of the resource; re-read it and retry.

WC215 — Unavailable

http · HTTP 503

A subsystem this route needs is not running in this process (for example the agent runtime), or has no room: at most max(32, workers × 8) behaviour runs go at once, and a run past that is refused rather than queued. Check the server log at boot; for behaviours, retry shortly or raise WEBCORTEX_MAX_BEHAVIOURS.

WC216 — Request body too slow

http · HTTP 408

The client announced a body but did not finish sending it within request_timeout (agent_timeout on agent, behaviour and flow routes). Send the whole body promptly, or raise the limit on WebCortex(...).

WC217 — Upstream response too large

http · HTTP 502

A proxied upstream answered with a body over its max_response_bytes (64 MiB by default). Raise it on app.upstream(..., max_response_bytes=...) or page the upstream's response.

WC218 — Too many connections

http · HTTP 503

The server already holds max_connections open connections (10,000 by default), WebSockets included. Retry shortly, close idle connections, or raise max_connections on WebCortex(...).

WC219 — Trace not found

http · HTTP 404

No trace with that id is held. Traces are kept in memory, newest first, up to app.tracing(keep=...) and not across a restart; GET /_webcortex/traces (or webcortex trace) lists the ones there are, and "latest" names the newest.

Agents, behaviours, flows and providers (WC3xx)

WC300 — Agent run failed

agent · HTTP 502

The run stopped on an error. The last step's error says which call failed; GET /_webcortex/status shows recent runs.

WC301 — Provider key not set

agent · HTTP 502

The model's provider needs an API key that is not set. Export ANTHROPIC_API_KEY or OPENAI_API_KEY (or the provider's api_key_env), use a local ollama/, or set WEBCORTEX_FAKE_PROVIDER=1 for tests. webcortex doctor checks every model.

WC302 — Undeclared provider

agent · HTTP 502

The model name has a prefix no provider answers to. Declare it with app.provider(name, base_url=...), or use ollama/, openai/ or anthropic/.

WC303 — Provider unreachable

agent · HTTP 502

The model provider could not be reached. Check the base URL and network; for Ollama run ollama serve (OLLAMA_HOST). webcortex doctor --online probes each provider.

WC304 — Provider returned an error

agent · HTTP 502

The model provider answered with an error status (bad model name, overloaded, invalid request). The message carries the provider's own detail.

WC305 — Unreadable provider response

agent · HTTP 502

The provider answered with something that is not its wire format. Check that the base URL points at the API, not a web page.

WC306 — Malformed agent request

agent · HTTP 400

An agent route takes {"input": str, "session_id"?: str, "reset"?: bool, "images"?: [...]}; input is required and must be a string.

WC307 — Tool not available to agent

agent

The model asked for a tool this agent was not given. Add it to the agent's tools=[...] if it should have it.

WC308 — Tool call failed

agent

A tool the agent called answered with an error; its code and message are in the step. The model sees the error and may retry.

WC309 — Approval required

agent

This tool is gated with approval="required". A human decides with POST /_webcortex/approvals/{id}; it cannot be called directly over MCP.

WC310 — Approval not found

agent · HTTP 404

No pending approval has that id: it was already decided, or it expired (approval_ttl_secs). GET /_webcortex/approvals lists the pending ones.

WC311 — Context provider failed

agent · HTTP 502

A context provider named in context=[...] failed while the run started. Check its SQL or Python handler.

WC312 — Response cut off at max_tokens

agent

The model ran out of max_tokens mid-answer, and no tool call in that response was run. Raise max_tokens, or reasoning="none" for local thinking models.

WC313 — Invalid image input

agent · HTTP 400

An image in images is not a supported {"$image": ...} marker, is too large, or names an internal host. Use webcortex.Image.

WC314 — Unknown tool

agent

No exposed tool has this name. tools/list (MCP) or GET /_webcortex/tools shows the names this caller can use.

WC315 — Flow step failed

agent · HTTP 500

A step of the flow failed or was refused; the message names the step. Run that tool alone to see its error.

WC316 — Watcher run failed

agent

A watcher's agent run failed; the insight carries the error. GET /_webcortex/status shows the watcher's recent runs.

WC317 — Malformed tool call

agent

The model asked for a tool with arguments that are not a JSON object (cut off, garbled, or a bare value), so the tool was not run. The model is told and may retry; a small local model that keeps doing it needs a larger max_tokens or a simpler input schema.

WC318 — Answer does not match the output schema

agent · HTTP 502

The agent has an output schema and its answer still did not match after being corrected twice. The failing steps list what was wrong. Simplify the schema, say in the system prompt what each field means, raise max_tokens if the answer is being cut off, or use a stronger model. A problem saying checking stopped after some number of steps means the schema's alternatives multiply at one place; give the union fewer, flatter members.

WC319 — No recorded response to replay

agent · HTTP 502

A run replayed from a cassette asked for a model response the cassette does not hold: the agent's system prompt, model, tools or options changed since it was recorded, or the run now takes a different path. If the change is intended, record again with webcortex eval --record.

WC320 — Unreadable cassette or eval

agent

An eval could not be run: its cassette file is not valid JSON or not a cassette this version reads, or the eval names a target that is not a tool. Delete the cassette and record again with webcortex eval --record, or fix the target in app.eval(...).

Budgets and limits (WC4xx)

WC401 — Rate limited

limits · HTTP 429

Too many requests from this caller. Wait for retry-after seconds, or raise app.rate_limit(per_second=..., burst=...).

WC402 — Token budget exhausted

limits

The run hit its token_budget (its own, or the request tree's shared one). Raise token_budget, use a cheaper model alias, or bound context with tool_result_limit / context_window.

WC403 — Nesting too deep

limits · HTTP 508

Agents, behaviours or flows called each other past max_invocation_depth: usually something calling itself. Break the cycle.

WC404 — Step limit reached

limits

The run used max_steps before the model stopped asking for tools. Raise max_steps, or give the agent fewer, sharper tools.

WC405 — MCP batch too large

limits

A JSON-RPC batch may hold at most 32 messages. Split it.

WC406 — Returned generator too large

limits · HTTP 500

A handler, behaviour or tool returned a generator (or other lazy iterable) that went past WEBCORTEX_MAX_RESULT_ITEMS (default 100000) or WEBCORTEX_MAX_RESULT_BYTES (default 64 MiB). A response is sent whole, so return a bounded result: page it, or raise the limits.

Devices, actuators and the emergency stop (WC5xx)

WC501 — Unknown device

devices · HTTP 404

No device has that name. Declare it with app.camera(name) or app.sensor(name); GET /_webcortex/devices lists them.

WC502 — Actuators halted

devices · HTTP 423

The emergency stop is engaged, so nothing that moves hardware runs. An operator releases it with webcortex release or POST /_webcortex/release (admin scope).

WC503 — No frame yet

devices · HTTP 404

The device has not sent a frame. Open /devices//connect on the camera, or push frames to its ingest route.

WC504 — Frame faster than max_fps

devices · HTTP 429

The device is sending faster than its max_fps; the frame was dropped. Slow the sender or raise max_fps.

WC505 — Invalid frame or telemetry

devices · HTTP 422

The frame is not a PNG/JPEG/GIF/WebP, is over max_frame_bytes, or the telemetry is not a JSON body (a body that is not JSON at all is answered 400; the rest 422).

WC506 — Camera unreachable

devices · HTTP 502

A pulled IP camera did not answer with a snapshot. Check its URL, its bearer_env, and that it is reachable from the server.

Authentication and security (WC6xx)

WC601 — Authentication required

auth · HTTP 401

This route needs a credential. Send the API key in the x-api-key header (or Authorization: Bearer ).

WC602 — Missing scope

auth · HTTP 403

The caller is authenticated but lacks a scope this route requires; the message names it. Use a key whose app.api_key(..., scopes=[...]) includes it.

WC603 — Invalid credential

auth · HTTP 401

The API key or token was not accepted (unknown, expired or malformed). Check the key, or mint one with webcortex keygen and register it with app.api_key(env_var, ...).

WC604 — Admin scope required

auth · HTTP 401

The /_webcortex control plane needs the 'webcortex:admin' scope once any auth is configured. Use an admin key: app.api_key(env, id=..., scopes=['webcortex:admin']).

WC605 — Cross-origin request refused

auth · HTTP 403

A browser on another origin sent a state-changing request or a WebSocket upgrade. List that origin in app.cors(...) if it should be allowed.

WC606 — CORS origin not allowed

auth · HTTP 403

The preflight's Origin is not in app.cors(...). Add it there.

WC607 — Needs an authenticated caller

auth · HTTP 401

Anonymous callers share one identity, so @principal-scoped data and agent sessions need a real credential.

WC608 — No authentication configured

auth

Every route is public. Add app.api_key('WEBCORTEX_API_KEY', id='service', scopes=[...]) before exposing the app beyond localhost.

WC609 — Unauthorized (raised by the app)

auth · HTTP 401

The app's own code answered 401 (for example a wrong password at login); its message says why. WebCortex's own credential checks answer WC601, WC603 or WC604 instead.

WC610 — Forbidden (raised by the app)

auth · HTTP 403

The app's own code refused this caller with 403; its message says why. A missing WebCortex scope answers WC602 and a cross-origin refusal WC605 instead.