Error Codes

Every error the platform can return, organised by the area that raises it: an agent command, an HTTP endpoint, or a socket. Each area has its own vocabulary, and the catalogue below holds all three.

Agent command errors

These appear as error.code in the error of a command response, and in the stored result of a failed command.

Code	Raised by	Meaning
`UNKNOWN_COMMAND`	Any unrecognised command name	The agent does not know the command. The message is `Unknown command: <name>`.
`MISSING_SCRIPT`	`shell`	No `script` argument was supplied.
`MISSING_PATH`	`open_serial`, `close_serial`	No `path` argument was supplied.
`MISSING_ARGS`	`serial_write`	`path` or `data` was missing.
`NOT_IMPLEMENTED`	`run_test_suite`, `upload_artifact`	The command is part of the contract but the agent does not implement it.
`EXECUTION_ERROR`	Any command	The handler threw. The message is the exception text.
`COMMAND_TIMEOUT`	Any command	The command exceeded its timeout.

The same set is produced by both delivery paths — the socket and the polling fallback — because both call the same handlers.

Two failures are reported through the output rather than through the result's status.

Failure	Result
The command exceeded its timeout	`status` is `timeout`, `output.exitCode` is `-2`, and `output.stderr` reads `Command timed out after <ms>ms`. The code `COMMAND_TIMEOUT` names the same condition.
The process could not be spawned	`status` is `error`, `error.code` is `EXECUTION_ERROR`, and `output.exitCode` is `-1`.

Result statuses

The status field of a command result takes one of three values.

Status	Meaning
`success`	The command ran and did what it was asked to do. `shell` also uses it for exit code `0`.
`error`	The command failed. `error.code` says why. A `shell` script that exits non-zero is reported as `error` with the script's own exit code in `output.exitCode`.
`timeout`	The command exceeded its timeout and was stopped. `output.exitCode` is `-2` and `output.stderr` reads `Command timed out after <ms>ms`.

The command row itself moves pending → in_progress → completed. A failed command is still completed: the result, including the error, is stored.

HTTP status codes

What the studio's REST endpoints return.

Status	Body	Where
`400`	`Missing agentId or command`	`POST /api/agents/command` — a required field is absent.
`400`	`Agent is offline`	`POST /api/agents/command` — no live socket for that agent.
`400`	`Agent is not active`	`POST /api/agents/command` — the stored status is not `active`.
`401`	`Invalid API key`	`POST /api/agent/auth` — the key matches no agent.
`403`	`invalid_code`	`POST /api/agent/register` — the code matches no licence.
`403`	`used`	`POST /api/agent/register` — the licence was already spent on another machine.
`403`	`revoked`	`POST /api/agent/register` — the licence was revoked.
`403`	`expired`	`POST /api/agent/register` — the licence has passed its expiry.
`403`	`invalid_credentials`	`POST /api/agent/register` — the `agentId` and `agentSecret` pair matches no agent.
`403`	`License has been expired`	`POST /api/agent/register` — the licence has passed its expiry.
`404`	`Agent not found`	`POST /api/agents/command` — no agent with that id.
`404`	`Agent or license not found`	`DELETE /api/admin/agents/{id}` — the id matches neither an agent nor a licence.
`500`	`Database not configured`	Any endpoint that needs the database, before setup has run.

Errors are returned as {"error": "…"} on most routes. POST /api/agent/register uses {"success": false, "error": "…"}.

Socket errors

A socket response that reports a failure carries ok: false and an error object with a code from the protocol's error vocabulary.

Code	Raised by	Meaning
`AUTH_FAILED`	The `auth` and `dashboard_auth` handshakes	The agent's id and secret did not match, or the dashboard's token did not. The socket is closed.
`PROTOCOL_VERSION_UNSUPPORTED`	The `auth` handshake	The agent speaks a protocol version the studio does not. The socket is closed.

A command that fails on the socket reports its code the same way — in the error of a command response whose ok is false.

Triage

Symptom	Start here
`Agent is offline`	The agent's socket is not connected. Check the agent log and the network path. See Agent Offline.
`Agent is not active`	The agent unregistered, or its licence was revoked and the row changed. Re-register it.
`Invalid API key`	The key in `data/agent.json` no longer matches the studio's `agents.api_key`. Register again to get a fresh pair.
`403` on registration	The licence is invalid, revoked or expired. Issue a new one from the admin screen.
`AUTH_FAILED` on an agent	The agent's `agentSecret` does not match `agents.agent_secret`. Re-register the agent to reissue both credentials.
`AUTH_FAILED` on a dashboard	The token the dashboard presented does not match `DASHBOARD_WS_TOKEN`. See Configuration.
`PROTOCOL_VERSION_UNSUPPORTED`	The agent speaks a protocol version the studio does not. Upgrade the agent and reconnect. See Version Compatibility.
`UNKNOWN_COMMAND`	The command name is wrong, or it belongs to a newer studio than the agent. See Version Compatibility.
`MISSING_SCRIPT`, `MISSING_PATH`, `MISSING_ARGS`	The command was sent without a required argument. See Command Reference.
`EXECUTION_ERROR`	Read `error.message`: it carries the text of the exception the handler raised.
`NOT_IMPLEMENTED`	The agent does not implement that command. Upgrade the agent, or do not dispatch it.
`timeout`	The command ran past its timeout. Raise the timeout, or make the script faster.