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.