Skip to content

Exit codes

fxv exits with 0 when a command succeeds and with a non-zero code when it does not. Most failures exit with 1. A few conditions that a script or integration is likely to handle differently have a code of their own, so the caller can act on them without parsing the error message.

Code Meaning What to do
0 The command succeeded. Nothing.
1 The command failed. This covers every failure without a code of its own, including a remote repository that could not be reached or read. Read the error message, which states the problem and, where there is one, the fix.
2 The command rejected its arguments: a required one is missing, two that cannot be combined were given together, or a value failed validation, such as a username with characters it may not contain. This is also the code for a command line fxv cannot parse, such as an unknown option. Correct the invocation. The message states which argument was rejected and why.
3 fxv upgrade --check completed, and a registered integration does not support the release it would install. Update the integration, or upgrade to a release within its range with fxv upgrade --to <VERSION>.
4 fxv doctor completed, and at least one check failed. Earlier releases exited with 2 for this case. Read the report, which suggests a fix for each failed check that has one. fxv doctor --fix applies the fixes that are safe to automate.
67 The command succeeded with warnings, which list what it could not do.
96 The repository uses an older format, and must be upgraded before this version of fxv can use it. Run fxv repo upgrade. See Upgrade Your Repository.
97 The remote endpoint answered, but there is no FlexVault repository at it. Create one there with fxv repo new, or check the endpoint URL if the repository should already exist.
98 A previous command was interrupted, or stopped because it could not change some files, so the workspace is in an inconsistent state. If the error lists files that could not be changed, fix the cause given for each. Then run fxv resume to finish the command, or fxv resume --rollback to undo it. See Recover an Interrupted Command.
99 Another fxv process, such as a command run from another terminal or an editor plugin, is using the workspace. The message includes that process's ID and command when they are known. Try again once the other command has finished. If no fxv process is running, fxv doctor --fix clears the lock it left behind.

Exit codes in JSON output

With --format json, a failed command prints an envelope whose message.kind is error. Its payload contains the error message and the same exit_code the process exits with, so a script reading the JSON does not need to check the process exit code separately. See Output Formats.

Codes 3 and 4 are different: the command completed and printed its normal report, and only the exit code says that the report contains a finding. A script that runs fxv doctor or fxv upgrade --check as a check reads the exit code for those two.

Code 67 also comes from a command that completed: a script can treat the operation as done, and check the warnings in its output.

The RPC server reports these same codes in its error responses, so a client can handle a failure the same way on either transport.