Errors

Failed requests return a JSON-RPC 2.0 error object:

code: an integer identifying the kind of error
message: a short human-readable description
data (optional): additional information whose shape depends on the code

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": { "sessionId": "sess_abc123def456" }
  }
}

Error Codes

Code	Message	Meaning
`-32700`	Parse error	The message is not valid JSON.
`-32600`	Invalid request	The message is not a valid request object, or a request other than `initialize` arrived before initialization.
`-32601`	Method not found	The receiver does not implement the method.
`-32602`	Invalid params	The parameters are malformed or contain a value the receiver does not support.
`-32603`	Internal error	The receiver failed unexpectedly.
`-32800`	Request cancelled	The request was cancelled.
`-32000`	Authentication required	The request requires authentication first.
`-32002`	Resource not found	A referenced resource, such as a session or file, does not exist.

Receivers MUST treat an unrecognized code as a generic failure. Implementation-specific errors SHOULD use codes outside -32768 to -32000, which is reserved for JSON-RPC and ACP.

Common Cases

Unknown Methods

A receiver that does not implement a method, or receives a capability-gated method it did not advertise, SHOULD respond with -32601.

Invalid Parameters

Malformed parameters and unsupported values get -32602. For example, an invalid session/list cursor, or an unknown configId or value in session/set_config_option. The same applies to an unknown mode in session/set_mode.

Unknown Sessions

If a session-scoped request names a session that does not exist or is not active on the connection, the Agent SHOULD respond with -32002 and set data.sessionId to the requested ID. A session is active once it is created, loaded or resumed on the connection, until it is closed. This applies to session/prompt, session/set_mode, session/set_config_option and session/close, and to session/load or session/resume of a session that does not exist. Deleting a session that does not exist still succeeds; see Deleting Sessions. Clients SHOULD respond with -32002 when fs/read_text_file names a file that does not exist, or a terminal/* method names an unknown terminal.

Requests Before Initialization

Agents SHOULD reject any request other than initialize that arrives before initialization completes with -32600.

Get Started

Protocol

Libraries

Error Codes

Common Cases

Unknown Methods

Invalid Parameters

Unknown Sessions

Requests Before Initialization

​Error Codes

​Common Cases

​Unknown Methods

​Invalid Parameters

​Unknown Sessions

​Requests Before Initialization

Error Codes

Common Cases

Unknown Methods

Invalid Parameters

Unknown Sessions

Requests Before Initialization