Troubleshooting
Start with a health report, then fix the reported cause.
Run the health checks
airship doctor
airship doctor --meshUse airship doctor --host box-a to isolate one remote host. Read the message and suggested command before trying repairs. --repair can change setup; inspect airship help doctor before using it.
Common fixes
| Symptom | Next step |
|---|---|
airship is not found | Add $HOME/.airship/bin to PATH and open a fresh shell. |
| Python or tmux is missing | Install Python 3.12+ and tmux 3.2+ on the affected host, then rerun doctor. |
| A remote host is unreachable | Confirm it is awake and test its SSH alias with BatchMode. |
| Runtime is missing or logged out | Install and sign in to Claude Code or Codex on that host. |
| No capacity | Inspect airship status --host all; free capacity or select another host. |
| Send reports busy or a dialog | Answer the dialog, wait for ready, or use send --queue. |
| A model is unverified | Refresh discovery with airship models ls --host box-a --refresh. |
| A permission change is not active | Check the unit’s badge; running sessions keep their flags until the required restart. |
Check a stalled session
airship status
airship attach helperRead the runtime’s current prompt. Detach with Ctrl B, then D. Avoid sending duplicate tasks just because a status update is delayed.
Recover a move
airship move ls --attention
airship move show <move-id>Replace <move-id> with the reported id.
| State | What it means | Next step |
|---|---|---|
| Rolled back | Work resumed on the source. | Fix the reported destination problem before retrying. |
| Frozen | The unit is running nowhere; source work is retained. | Follow the hint, usually airship move resume <move-id>. |
| Cleanup pending | The destination is running; source cleanup is incomplete. | Use airship move resume <move-id> to finish. |
| In progress | A move is still active. | Use airship move wait <move-id>. |
Do not start a second copy or force a rollback while the destination might still be running. Inspect the move report’s recovery instructions.
App connection errors
Use the inline hint and copyable command. Check the CLI with airship doctor, then reconnect in the app. The app’s Settings › General › Run self-test runs the CLI tour; Help › Take the Tour is an in-app orientation.