Troubleshooting

Start by checking the agent is actually running: spadeide status on the host, or the menu-bar popover on macOS.

The iPad cannot find the host on my own network

Check	What to do
Both on the same network?	Guest Wi-Fi and "client isolation" on many routers block devices from seeing each other. Switch the iPad to the main network.
Agent running?	`spadeide status`. If not: `spadeide`.
Firewall	Allow `7422/tcp` from your LAN and `5353/udp` for discovery. On macOS, allow incoming connections when prompted.
mDNS on Linux	`sudo apt install avahi-daemon avahi-utils`, then restart the agent.
VPN on the iPad	A full-tunnel VPN routes LAN traffic away. Turn it off to test.

As a fallback, paste the pairing URL by hand — it contains the address and fingerprint.

Pairing fails

"Bad pairing secret" — the code is single-use and expires in ten minutes. Generate a new one (spadeide, or New pair code in the popover).
Certificate mismatch — the agent's identity changed, usually because ~/.spade-agent/certs/ was deleted or the host was reinstalled. Remove the host on the iPad and pair again. On a system install the certs live under /var/lib/spade-agent/.
Nothing happens after scanning — check the iPad can reach the address in the URL at all; a stale IP in an old QR is common after a DHCP change.

Only after sudo ./install.sh --system (or the privileged systemd unit). A normal user install never shows this sheet — see which install.

Symptom	What to do
Connected, then “unix login required” / sheet with username + password	Expected once per tablet. Use a real host account (not `root`). Password goes over the already-encrypted session and is not stored.
Wrong password / refused / disconnects	Reconnect and try again. Confirm the account can log in locally (`su - user` or SSH). Locked / expired / deleted accounts fail.
Asked for Unix login again after it worked	Password changed, account locked/deleted, or UID recycled. Enter the new credentials (or a different account).
No Unix login sheet, but “unix login required” in the UI	Update the iPad app — older builds could skip presenting the form. Force-quit SpadeIDE and reconnect.
Terminal: `permission denied` for docker / devices	The shell has that Unix user’s normal groups only. Add the user to the group on the host (`usermod -aG docker …`), then log out/in Unix-wise and reconnect the tablet.
Cannot browse outside home	By design on a system install — the session is jailed to that user’s `$HOME`.

Pairing QR for a system install: sudo spadeide pair --no-start (do not start a second agent with interactive sudo spadeide).

Remote access does not work

Symptom	Cause
"Remote access is turned off on host"	Exactly what it says: `spadeide remote on` on the host.
"Host is offline"	The agent is not registered — it is not running, or it lost internet.
"Could not reach rendezvous"	The iPad cannot get to the introducer. Check the Rendezvous URL in Settings, or the network you are on.
Connects, but always relays and feels slow	Direct needs UDP. Carrier-grade NAT and networks that block UDP force the relay. If you self-host, confirm 443/udp is open.
Worked yesterday, not today	Handles rotate hourly — a clock that has drifted breaks lookup. Check the time on both machines.

Connection keeps dropping

Moving between Wi-Fi and cellular, or the iPad sleeping, will reconnect automatically — your tabs, workspace and unsaved edits survive. If it drops repeatedly while stationary, check the host is not sleeping: a Mac that suspends takes the agent with it.

# macOS: keep the machine awake while the agent should be reachable
caffeinate -s

Git says it cannot authenticate

Git runs non-interactively, so anything that would prompt for a password fails instead of hanging. Run the command once in the terminal — inside SpadeIDE is fine — so your credential helper or SSH agent caches it, then retry from the UI.

Where the logs are

# the agent
tail -f ~/.spade-agent/agent.log

# Linux, under systemd
journalctl -u spade-agent -f
journalctl --user -u spade-agent -f

# self-hosted rendezvous
journalctl -u spade-rendezvous -f

In the app, Settings → Events shows connection and transport notes from the iPad's side — which path it chose and why a connection failed.

Starting over

spadeide reset        # forget every paired device on the host
# then remove the host in the iPad app and pair again

To put a new Linux binary on the host without losing pairings, see reinstalling on a server. Wiping ~/.spade-agent is a new identity — every iPad must pair again.