Error code index — look up meaning and next step by code

Use this page when you have an error.code or a displayed code and want its meaning and next step. To search by symptom, read Troubleshooting.

Which section to read depends on where you saw the code. The same failure can look different in the WebUI, chat, and aachat.

In every case, do not decide from the code alone. Also read message and hint. If you do not know whether a change succeeded, check whether the first request was accepted before repeating it.

Reading server error codes

When the aachat API server fails, it returns an HTTP status and a body shaped like {"error": {"code": ..., "message": ...}}. error may include input (the value received) or existing_session_id. Some failures also add data to the body. Most code values are uppercase (VALIDATION_ERROR, NOT_FOUND, SESSION_NOT_RUNNING, and so on). Some for Projects, Asks, and Workflows are lowercase (project_not_active, ambiguous_id, draft_version_conflict, and so on).

The same failure shows a different code depending on where you read it.

chat maps codes by these rules.

• HTTP 400 and 422 become invalid_argument. The exceptions are ambiguous_id, AMBIGUOUS_PROJECT, AMBIGUOUS_USER, USER_NOT_FOUND, REPLY_TARGET_NOT_FOUND, and INVALID_REPLY_TARGET, which each become the lowercase code of the same name
• 401 becomes token_required, 403 becomes not_authorized (except dedicated codes such as ADMIN_REQUIRED), 409 becomes conflict, 429 becomes network_error, and 5xx becomes server_error
• 404 depends on words in message. If it contains session, it becomes session_not_found. If it contains agent, agent_not_found. If it contains blueprint or repository, unexpected_response. Otherwise, project_not_found
• Structured server codes are checked before the status fallback. For example, VALIDATION_ERROR becomes invalid_argument even with HTTP 413. Without a matching code, statuses such as 410, 413, and 426 become unexpected_response
• Workflow validation and state codes (invalid_workflow_yaml, draft_version_conflict, and so on) pass through in lowercase for Workflow commands
• Some change operations become operation_outcome_unknown when no response arrived after sending, or when they got HTTP 408, 429, or 5xx: project create, project assign, workflow init, workflow run (including --wait), workflow retry, workflow complete, wait, trigger create, and trigger run. Workflow change operations do the same on connection failure. Do not create a new request; follow that command's message and hint. If commands is present, read what each command does (Retrying the same request)

Recovery from operation_outcome_unknown depends on the command:

• For workflow init/run/retry and wait, use the recovery command in commands exactly as shown, keeping the same nonce, arguments, and input. It may perform a change; do not generate a new nonce
• For workflow complete, even without commands, resend the exact same payload through the same closed non-interactive input until the response contains accepted:true. Acceptance is separate from Workflow or product success
• For project create and project assign, commands is not required. Follow hint: keep the same arguments and stdin for create, or the same Project and agent for assign. Do not add a nonce option that the command does not support
• For trigger create and trigger run, the list/show commands are reads for checking the current Trigger. Check that state before deciding what to do next

If the "In chat" column says "Same", the server code appears as is. "—" marks codes that chat never receives, such as WebUI-only or human-only operations.

General codes

These codes can come from any feature. First judge roughly by HTTP status, then read the cause in message.

Permissions and scope

ask_cancel_not_authorized is in Asks and waits.

Project

Archive and deletion run asynchronously. Failures along the way are not error responses. They stay in the Project's processing state and appear in the WebUI as Could not complete Archive / Deletion failed.

Session

Live view codes

These come from fetching the WebUI live view. chat never receives them. The screen shows text such as Live updates could not keep up. or Could not update the live view. (Live view and saved tool output).

Result report item codes

chat result report returns per-item results in data.items[]. A failed item has status: error with code, message, and retryable. If even one item fails, the overall error.code is result_report_incomplete (Read the report result).

If the report itself is not accepted, you get an overall error, not item codes. From outside a turn it is session_not_running. From an old runtime it is the server's stale_bootstrap_generation (conflict in chat; see Session).

Asks and waits

Documents, sync, and Wiki

Sync failures from aachat up for documents, HTML, Database migrations, and the Wiki do not appear as error responses. They appear in _errors.md in each folder. Documents and similar use the form sync write attempt API error <status> (<code>): <message>. The Wiki uses Wiki write failed (HTTP <status>, <code>): <message>.

Media and attachments

Errors when sending

When you add attachments or Project Media to a Session instruction or message and there is a problem, INVALID_ATTACHMENT (400) is returned. In chat it becomes invalid_argument (failures of the upload itself, such as chat session run --attach, are attachment_upload_failed).

Some other failures put a code at the start of message.

Media and attachment failure states

When Project Media becomes failed, the reason stays in the Media's error.code and error.message. Failed Session attachments use the same codes. Read them in the WebUI Media tab or the attachment display.

If preparing an add in the WebUI fails, upload_errors[] returns upload_temporarily_unavailable (temporary; upload again), upload_preparation_failed (check permissions, then upload again), or upload_not_prepared (preparation did not finish; upload again). For media_unavailable, returned when a Session reads Media that is not in the same Project's ready list, read chat CLI error codes.

Project HTML

Project HTML build failures appear as descriptive text, not codes, in the HTML tab's diagnostics. Search by the shape of the text.

Sharing and preview operations return the following text.

Project Database

In chat db, only DATABASE_SQL_EXECUTION_FAILED and DATABASE_RESULT_TOO_LARGE become lowercase codes of the same name. The others become the common code for their HTTP status, and the next step goes in hint.

Workflow

Definition and input validation

For Workflow commands, the codes below appear in chat in lowercase as is. The exit code is 2, except invalid_output and rendered_prompt_too_large, which are 1. The location is in got and the reason is in message.

Drafts, publishing, Runs, and completion

Step failure codes

These stay in a failed Step's error.code and error.message. Read them in the Run detail or chat workflow status (Read the Run and recover). For config_not_offered and others from a Session that failed during startup preparation, read Session failures and startup codes.

Triggers and Webhooks

When a Trigger is paused, pause_reason gives the reason. The values are manual, project_inactive, permission_revoked, target_unavailable, input_contract_invalid, and workflow_archived. Recovery for each is in Recover from conflicts, pauses, and unknown outcomes.

A firing record (occurrence) may have a reason: previous_run_active (skipped because the previous work is still running), superseded_during_downtime (schedules missed while stopped were skipped together), or previous_run_superseded (accepted, replacing the previous work). For a failed occurrence, reason holds text explaining why it paused.

Messages and recipients

Secrets (Tools > Secrets)

Operations in Tools > Secrets in the WebUI return a response whose body is only {"code": ...}. No description is included. aachat running on the chosen Computer stores values and grants access. chat does not use these (Environment).

Skill

GitHub integration

GitHub API failures are mapped by GitHub's status. 401, 403, 404, and 429 become aachat's UNAUTHORIZED, FORBIDDEN, NOT_FOUND, and RATE_LIMITED, with message starting with GitHub authentication failed., GitHub access denied., GitHub resource not found., or GitHub API rate limit exceeded. Please try again later.. Everything else becomes GITHUB_ERROR (502).

An UNAUTHORIZED whose message starts with GitHub is a GitHub authentication problem, not an aachat sign-in problem. In chat both become token_required, so tell them apart by message.

External AI connection (OAuth)

The OAuth entry points for Connected apps (remote MCP) return failures in the standard OAuth form {"error": "<code>"}. The codes are invalid_request, invalid_client (401), invalid_client_metadata, invalid_grant, invalid_scope, unsupported_grant_type, temporarily_unavailable, and server_error (503). The external AI client handles these. As a user, redo the external AI connection (Connected apps).

aachat CLI error codes

On failure, ordinary aachat commands return one JSON object on stdout. Its shape is {"ok": false, "error": {"code": ..., "message": ..., "field"?, "expected"?}, "data"?, "warnings"?, "next_actions"?}. Read next_actions first, then message. data is present only when there are partial results or change.state (not_applied, applied, unknown).

The exit code is 2 for invalid_argument, missing_argument, and conflicting_arguments, and 1 for other failures. aachat up, interactive aachat support, aachat manage-agent, aachat env --interactive, and aachat doc check --hook do not return JSON (Output format).

Server codes (FORBIDDEN, AGENT_RUNTIME_OFFLINE, and so on) are mapped in aachat to the small set of codes in the table below. The server's description stays in message. To look up the original server code, read the server API code sections.

chat CLI error codes (inside a Session)

On failure, chat inside a Session returns one {"ok": false, "error": {"code": ..., "message": ..., ...}, "data"?: {...}} on stdout. When available, error includes command, project, name, field, got, expected, candidates, available_agents, commands, reply_to, and hint. commands is an array of command locators you can run next.

message is the server's description if there is one, and otherwise guidance on the next step. Only when the server's description is in message does the guidance appear separately in hint.

The exit code is 2 for invalid_argument, missing_argument, conflicting_arguments, and Workflow validation errors (invalid_input, invalid_workflow_yaml, invalid_bundle_path, bundle_too_large, cyclic_dependency, unknown_step_reference, invalid_prompt_variable, missing_completion_instruction, invalid_completion_instruction), and 1 otherwise.

chat maps server codes to lowercase codes. For example, the server's AGENT_RUNTIME_OFFLINE becomes agent_runtime_offline, and FORBIDDEN becomes not_authorized.

Common codes

Codes by feature

aachat doctor checks and codes

Each item in data.diagnostics.issues[] from aachat doctor (checks[] with --view checks) has an id and a code. By default code equals id. It takes a different value only when the cause is known. Read the state in state (pass, fail, unknown, skipped) and the severity in category (blocker, preservation, maintenance, information). How to read overall is in Diagnose first.

If the diagnosis itself was interrupted, or child process cleanup could not be confirmed, it returns {"ok": false} with exit code 1. error.code is internal_error, and error.message is cancelled or probe_cleanup_unverified. Items already collected stay in data.

Checks (id)

Codes when a check did not finish

Sync codes

Projection placement codes

These appear in the code of project_workspace_host and project_workspace_repo, and at the start of projection.reason in aachat status.

Workspace maintenance codes

These appear in the code of session_workspace_maintenance and session_workspace_retained. None of them permits deletion. Preserve your local work before acting.

The next step appears in each item's next_actions. Commit and push uncommitted or unpushed work, or save it elsewhere. For "cannot be read" and "cannot be confirmed" items, check permissions and paths, then run aachat doctor again.

aachat status warnings[] and state values

aachat status may return warnings[] and next_actions even on success. The next step appears in next_actions.

When projection.state is blocked, projection.reason has the form <code> at <path>: <description> Next: <next step>, and <code> is one of the projection placement codes. How to read error is in aachat up fails to start or stops midway.

Launch Report categories

aachat up writes each agent's startup result to up.log as a Launch Report. A failed agent shows Error [<category>]: ... and action: under [failed] <agent>. Even with an agent marked [failed], aachat up itself keeps running.

When aachat up itself fails and exits, the same category appears in up.log, and the exit code is determined by the category.

For what to do per category and how to read Runtime Health, read aachat up fails to start or stops midway.

Session failures and startup codes

When a Session fails during startup preparation, step (the preparation stage that failed), message, code, and subject stay in the Session's runtime_facts.bootstrap.failure. The WebUI shows message and Initialization step: <step>. code is one of the four below and is absent for other failures. All of them are failures before the prompt is sent. In a Workflow Step, the same codes appear as the Attempt's failure. When a Step Session fails without one of these codes, the Attempt's failure code is session_failed.

In aachat session list and session read results, a failed Session's error is {"code": "session_failed", "message": ...}. In the list, attention.items[].code is permission_pending (waiting for a permission answer), submission_pending (there is an unprocessed request), or failure (it failed). For how to continue a failed Session, read A Session failed or stopped midway.