Every failure the CLI reports carries a stable snake_case code, in the
Error: line in text mode and as the code field under --output json.
Scripts decide on the code and the exit status, never on
the message. This page lists the codes you are most likely to meet.
| Code | Exit | Meaning | Fix |
|---|
not_signed_in | 4 | The profile has no sign-in. | airdress auth login |
sign_in_expired | 4 | The refresh token was refused; a browser login is needed. | airdress auth login |
profile_not_found | 4 | The --profile named does not exist. | airdress profile list |
machine_authorization_expired | 4 | An approved machine’s approval lapsed. | Renew it from the machine (for a shell host, airdress shell host reauth), or approve it again. |
| Code | Exit | Meaning | Fix |
|---|
capability_not_granted | 3 | A function asks for a capability its manifest does not grant. The refusal names the spec.capabilities path. | Grant it in function.yaml, or remove the request from function.json. |
resource_forbidden | 3 | The caller (often a CI machine) has no grant for this action on this resource. | Grant the action, or use your own sign-in. |
signer_not_this_client | 3 | Your signing key is not in the function’s signer set; the refusal lists the members. | airdress fn signers add <name> --key <hex>, by someone already allowed. |
publication_blocked | 3 | The owner blocked this person’s public name and photo. | Ask the airdress owner. |
not_enabled | 3 | The feature is switched off on this airdress (for example shells in preview). | Ask the airdress owner, or contact support. |
confirmation_declined | 3 | You answered No at a prompt. | Run it again and answer y. |
| Code | Exit | Meaning | Fix |
|---|
source_base_stale | 6 | The function moved since the version you named with --based-on. Both versions are printed; it is never retried. | Re-read what runs (airdress fn versions <name>), rebase, deploy again. |
epoch_conflict | 6 | Another device committed a change to the same conversation first. | Retry; the client catches up first. |
root_key_mismatch | 6 | This device’s key does not match the airdress’s current root. | Rejoin the device from a phone of yours. |
fencing_stale | — | An agent bus tool write came from a session that lost its claim (MCP tools have no exit code). | Claim again with bus_claim before writing. |
| Code | Exit | Meaning | Fix |
|---|
usage | 2 | The command line is wrong. | airdress <command> --help |
signer_unavailable | 2 | No signing key was given. | --signing-key <file> or AIRDRESS_FUNCTION_SIGNING_KEY |
confirmation_required | 7 | A destructive command ran without a terminal or under --output json. | Pass --yes deliberately. |
unreachable | 5 | The other end could not be reached. | Check your network, then troubleshooting. |
timeout | 5 | No answer in time. | Raise --timeout, or check the status page. |
http_<status> | varies | An HTTP status with no more specific code. | Read message and hint. |
internal | 1 | Unexpected; likely a bug. | Send airdress version and the output to support@airdress.co. |
