Local API errors
Error envelope, request correlation, timeouts, and recovery behavior.
Local API errors
A rejected request returns one newline-delimited JSON object with an error member where a successful response would carry result:
{
"id": "example:read",
"error": {
"code": "pane_not_found",
"message": "pane p_1 not found"
}
}id normally matches the request. A request that cannot be decoded has an empty id because the server cannot safely recover the caller's identifier.
Error fields
| Field | Meaning |
|---|---|
id | Caller-selected request identifier, or an empty string when decoding failed before correlation. |
error.code | Stable machine-oriented category. Handle this value in automation. |
error.message | Human-oriented context. Display or log it; do not parse it as a protocol. |
Common categories
| Category | Meaning | Recovery |
|---|---|---|
invalid_request | The first line was not a valid request envelope or parameter shape. | Correct the request using the schema for the target product version. |
*_not_found | A workspace, tab, pane, agent, group, plugin, or other target no longer exists. | Refresh state and choose a current identifier. |
invalid_regex | A wait or subscription pattern could not be compiled. | Correct the pattern before retrying. |
timeout | A wait condition did not become true before its requested deadline. | Reconcile current state, then retry only if the operation is safe to repeat. |
unsupported_* | The running mode or platform does not provide the requested operation. | Inspect ping capabilities or use a supported mode. |
internal_error | The server could not complete or encode the operation. | Preserve the code and message, inspect logs, and avoid blind retries for mutating operations. |
Method-specific codes are not a closed enum in schema version 1. Retain unknown codes and use the error envelope; do not treat the categories above as exhaustive.
Execution-host failures
Remote placement never falls back to the Local Execution Host. A connection, path, worker capability, or runtime failure keeps the requested execution_host_id and path in the error context.
| Code | Meaning | Recovery |
|---|---|---|
connection_profile_not_found | A lifecycle action named an unknown SSH profile. | Refresh connection.list and use a current profile_id. |
connection_profile_invalid | Profile identity, target, name, or suggested path is invalid. | Correct the profile fields. Do not include credentials in the profile. |
connection_profile_referenced | A live or persisted resource still uses the profile's execution host. | Complete the cross-session retirement workflow before deleting or changing the binding. |
connection_profile_save_failed | The coordinator could not persist the catalog change. | Inspect the message and coordinator filesystem permissions before retrying. |
connection_profile_delete_failed | An unreferenced profile could not be removed from the catalog. | Inspect the message and coordinator filesystem permissions before retrying. |
connection_retire_host_invalid | A retirement request supplied an invalid execution host id. | Refresh connection.list and submit its exact execution_host_id. |
connection_retire_host_mismatch | The supplied host id does not match the profile's current binding. | Refresh connection.list. Do not retire a host through a stale profile binding. |
connection_retire_persist_failed | Retirement changed the session but could not persist the fenced state. | Stop mutation, preserve the error, and repair session persistence before retrying. |
execution_hosts_unavailable | The running mode has no execution-host manager. | Run the operation through a normal session server that supports execution hosts. |
invalid_agent_location | An agent location contains an invalid host id or host path. | Submit one complete location or a legacy local cwd. |
agent_placement_conflict | Agent placement selectors conflict. | Correct the target workspace/tab or remove the cwd/location conflict. |
workspace_create_failed | Workspace placement or its initial terminal launch failed. | Reconnect the named host or correct its host-native path, then submit a new request. |
tab_create_failed | Tab placement or its initial terminal launch failed. | Reconcile the target workspace and host, then retry with a new request id. |
pane_split_failed | The source host is unavailable or the new terminal failed. | Restore the source host connection or supply a valid explicit location. |
Remote creation errors preserve the requested placement so callers can show a retryable unavailable resource or reconcile partial creation explicitly. A lost response remains ambiguous; reconcile current resources before retrying a mutating request.
Connection failures
A missing socket, refused connection, empty response, invalid JSON response, or connection timeout is a transport failure. It does not produce an API error envelope. Check that the intended session is running and that the client resolved the same socket path. A lost response does not tell you whether a mutating request completed; reconcile state before retrying.
Streaming failures
events.subscribe validates every requested subscription before acknowledging the stream. A validation error returns an error response and closes the connection. After acknowledgement, an error line with an empty id means the server could not encode or maintain the event stream; reconnect and reconcile against current state.
Last updated on