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 layout 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.

Errors from a command¶

When a method that runs a command fails, the server classifies the failure the same way the command line does, and reports that classification in the error:

• code follows the exit code the command would have exited with: -32602 for a rejected argument, which exits with 2, and -32000 for everything else.
• message is the text the command would have printed, including its advice on what to do.
• data is an object with kind, the class of failure, and exit_code, the code the command would have exited with. Some failures add error_data, structured detail about the condition, such as what is known about the interrupted command behind exit code 98.

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Workspace is locked by another process (no lock info available).","data":{"exit_code":99,"kind":"FxvWorkspace"}},"id":2}

A client that already handles the CLI's exit codes can branch on exit_code and treat the JSON-RPC code as a coarse grouping.

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

Rejected arguments¶

A rejected argument is reported with -32602, a message giving the detail, and data with kind and exit_code as above. It covers:

• An unknown or misspelled parameter name. The message identifies the field and lists the valid ones.
• A missing required parameter, such as changeinfo without change_id.
• A combination the method does not allow. The message gives both the wire spelling and the command line flag.
• A value that fails validation, such as a username with characters it may not contain. kind is then the class of the check that rejected it, FxvRepo for a username, and exit_code is still 2.

{"error":{"code":-32602,"message":"unknown field `skipScan`, expected `skip_scan` or `skip_remote_update`","data":{"exit_code":2,"kind":"InvalidArguments"}}}

{"error":{"code":-32602,"message":"published_only (--published-only) and draft_only (--draft-only) are mutually exclusive","data":{"exit_code":2,"kind":"InvalidArguments"}}}

A rejected argument is answered before the workspace is loaded, so the request changes nothing.

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 has two further layouts, for requests rejected before any method runs. 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"}}}

Positional parameters, meaning a params that is an array rather than an object, get reason and hint:

{"error":{"code":-32602,"message":"params must be a JSON object","data":{"hint":"pass an object of named fields instead, e.g. {\"skip_scan\": true}","reason":"positional (array) params are not supported; parameters are named, and their order is not part of this API"}}}

-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.