Errors

Error handling in the Agent Client Protocol

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 and -32899 to -32800, which are reserved for JSON-RPC and ACP. ACP takes -32800 (Request cancelled) from the second range, which LSP also reserves.

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 and session/set_config_option, and to session/load or session/resume of a session that does not exist. Closing or deleting a session that does not exist still succeeds; see Closing Active Sessions and 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.