Errors and what to do
When a command fails, af exits with a non-zero code and, with --json, prints {"ok": false, "error": {"code", "message", "hint"}}. Find the code below and do what the last column says. HOST_FULL also carries retryAfterSeconds.
| Exit | error.code |
Means | Do |
|---|---|---|---|
| 2 | USAGE |
Bad flags or name | Fix the call; the command reference |
| 3 | NOT_FOUND |
No such Machine in your Lane | af list --json |
| 4 | LANE_LIMIT |
Your Lane’s cap would be passed | Delete something you made (a stopped Machine still counts), use a smaller size, or tell the user (your admin can raise caps) |
| 5 | HOST_FULL |
The server is full | Wait retryAfterSeconds once, or use a smaller size, or stop. Never loop |
| 6 | UNREACHABLE |
Tailscale or the server is down | af doctor --json; tell the user. Use your fallback (GitHub-hosted runners) |
| 7 | NAME_TAKEN |
The name exists with another kind or size | Pick another name, or af … show it |
| 8 | RESTART_REQUIRED |
The change restarts a running Box | Ask the user; repeat with --restart |
| 8 | CONFIRM_REQUIRED |
A delete or restore without --confirm <name> |
Only when the user says so |
| 9 | AUTH |
Certificate missing, expired or revoked | Tell the user (af login) |
| 10 | CANT_SHRINK_DISK |
Disks only grow | Keep the size, or make a new Machine |
| 11 | FORBIDDEN |
Your certificate may not read or change that Lane’s keys | Stay in your Lane (the agent rules); if it is yours, tell the user (af login) |
| 12 | NO_KEYS |
A Box would have no SSH key: your Lane has none, and no GitHub user’s keys either | af keys add ~/.ssh/id_ed25519.pub (SSH keys), then repeat the create |
| 1 | INTERNAL |
Anything else | Retry once; then tell the user with the message |
Still stuck? See Troubleshooting and FAQ.