Exit Codes
FlexBlock refuses rather than guesses, and the exit code names the missing state. Every flexblock command exits with one of these codes, so scripts and systemd can tell a transient failure from one that a retry will not fix. Nearly every refusal message also names the state it found, the state it needed, and the flag that would override it.
Exit code table
Section titled “Exit code table”| Code | Meaning | Retry? | Usual remedy |
|---|---|---|---|
| 0 | Success | — | — |
| 2 | Usage error | No | Fix the command line. wipe with no terminal refuses with this code; add -y. |
| 3 | Internal error | Yes | Retry. For detail, raise the log level with --log-level debug. |
| 4 | Device I/O error on the cache device or the ublk device | Yes, after checking the device | Check the device. If update --device-size reports a partial resize, follow the step the message names: re-run update --device-size, or restart the daemon. |
| 7 | Written by a newer build | No | Upgrade flexblock. |
| 8 | Declined at the prompt | No | Nothing to fix; run again and confirm if you meant it. |
| 9 | The volume and this device disagree | No | Run show --remote. The refusal names the fix: attach the right device, --replace-ublk, or the matching grant. |
| 10 | A prerequisite failed (preflight) | No | Fix the prerequisite. Often ublk_drv is not loaded, or the command was not run as root. Other causes include missing bucket permissions, a store that does not enforce conditional writes, and memory (see --allow-overmemory). |
| 11 | No flexBlock cache on this device, or no volume at the prefix | No | The device was never attached, or a different device was named. Run attach, or init, first. |
| 12 | Busy: a daemon is serving | No | Find the daemon with show, which reports its PID, and stop it with SIGINT if it should not be running. |
| 13 | Owned elsewhere | No | Detach it on the owning host first, or give up a superseded cache with detach --allow-dirty-loss. Ownership keeps two hosts off one volume. |
| 14 | Object storage error | Yes | Retry. Check flexblock_obj_errors_total and flexblock_obj_retries_total for a bucket problem. |
| 15 | Refused as unsafe | No | The message names an override flag when one exists. Use it only once you understand what it discards. |
| 16 | Not cleanly stopped. Also returned by start when a stop runs out of --shutdown-flush-timeout with data left, or a queue thread fails. | Yes | Run start to recover, then stop it with SIGINT; raise --shutdown-flush-timeout if the flush ran out of time. |
| 17 | License | No | Check --grant-file and install a valid grant. An expired grant still serves, throttled. |
| 18 | The prefix already holds data | No | Use a different prefix, or if the objects are a dead flexBlock volume, wipe --allow-unverified with that grant. Nothing overrides this check. |
Under systemd
Section titled “Under systemd”The systemd unit lists the non-retryable codes start can return in RestartPreventExitStatus, so systemd does not loop on failures a restart cannot fix. See Running Under systemd.