Errors¶

A failed request produces a response with an error object in place of result. This page documents the codes the server uses and what each one contains.

{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found: blame","data":{"method":"blame"}},"id":2}

The error object has three fields:

• code - an integer from the table below. This is what a client should branch on.
• message - a human-readable description. Useful in logs and diagnostics; do not parse it or match on its text, which can change.
• data - optional, and its shape depends on the code. Present on most errors.

Error codes¶

The first five are the standard JSON-RPC 2.0 codes. -32000 is application-defined, and the range -32000 to -32099 is reserved for finer-grained codes later, so treat any code in that range as an application error rather than testing for -32000 exactly.

Application errors include a kind¶

An application error is one where the request was understood and the operation was attempted, but it did not succeed: a user that does not exist, a repository that cannot be reached, a file that cannot be read.

The data object contains a kind field identifying the class of failure, so a client can react without parsing message:

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Workspace error: Fxv Repo error: A user with the name 'dave' already exists","data":{"kind":"FxvWorkspace"}},"id":2}

kind is one of Io, FxvMultiCas, FxvRepo, FxvWorkspace, HttpManager, or Anyhow. Treat an unrecognized value as a generic failure rather than an error, since new kinds may be added.

What data contains for the other codes¶

-32601 reports the method that was not found:

{"error":{"code":-32601,"message":"Method not found: blame","data":{"method":"blame"}}}

-32602 takes one of three shapes. An unknown parameter name gives the serde message, which names the offending field and lists the valid ones:

{"error":{"code":-32602,"message":"Invalid params","data":"unknown field `skipScan`, expected `skip_scan` or `skip_remote_update`"}}

A working_dir parameter gets a dedicated error, with field, reason, and hint:

{"error":{"code":-32602,"message":"working_dir is not accepted as a request parameter","data":{"field":"working_dir","hint":"start the server with `fxv rpc --working-dir <PATH>` instead","reason":"the server's working directory is fixed when the server starts"}}}

Parameters that are individually valid but cannot be combined give the explanation as a string, naming both the wire spelling and the CLI flag:

{"error":{"code":-32602,"message":"Invalid params","data":"Error: published_only (--published-only) and draft_only (--draft-only) are mutually exclusive"}}

-32700 and -32600 contain a description of what could not be read, as a string:

{"error":{"code":-32600,"message":"Invalid request","data":"missing field `jsonrpc`"}}

The one exception is a jsonrpc field present but not equal to "2.0", which is reported with no data at all. Treat data as optional on every code.

The connection survives every error¶

No error class ends the connection. A malformed line, an unknown method, or a failed operation is answered and the server goes on reading. A client does not need to restart the server after a failed request.

Errors and the request id¶

An error response echoes the request's id wherever the server was able to read one, including when the request was otherwise unusable. A request missing its jsonrpc field still comes back with its own id:

{"jsonrpc":"2.0","error":{"code":-32600,"message":"Invalid request","data":"missing field `jsonrpc`"},"id":8}

The id is null only when no id could be recovered, which means the line did not parse as JSON at all, or parsed as a batch. A client waiting on a specific id should also watch for a null-id error response, since that is the only signal it will get that a line it sent was unreadable.

Failures before the connection starts¶

A server that cannot start produces no JSON-RPC error at all, because there is no connection to send it on. It reports on standard error and exits non-zero instead, so a client should treat an immediate exit as a startup failure rather than waiting for a response that will not come. See Startup failures.