# Troubleshooting ## RSA keys are not supported Tessera can't generate or import RSA keys: the current SSH stack can only offer the deprecated RSA/SHA-1 signature. Generate an [Ed25519 key](https://bambouville.com/docs/keys/#generating-a-key) instead — every modern OpenSSH server accepts it. RSA keys left over from older versions are shown disabled. ## Mosh won't connect - Is `mosh-server` installed on the server? - Can UDP reach the server? Some firewalls and most NATs block it; mosh needs UDP ports 60000–61000 by default. - Over a [jump host](https://bambouville.com/docs/connections/#jump-hosts): mosh's UDP can't traverse bastions. Tessera warns ("mosh is unreachable through the jump chain…") and falls back to SSH. ## Forwarding refuses a local port The iOS sandbox can't bind ports below 1024 — pick a higher local port. Local ports also can't repeat within one host. See [port forwarding](https://bambouville.com/docs/port-forwarding/). ## Forwarding is disabled on a Mosh host With transport mosh and **custom** launch mode there is no SSH connection to carry forwards. Switch the launch mode to **auto-tmux** or **named tmux** — those keep an SSH side channel that forwarding rides on. ## A connection sits at "connecting" or "starting tmux" Wait twelve seconds: the launch overlay names the stage it's stuck on and offers **edit host**, **retry**, and **back** — no more indefinite spinner. If tmux itself is the problem (not installed, can't start, or the host's dotfiles already launch tmux at login), Tessera drops to a plain shell with a banner naming the reason. And if a session attaches but the screen stays blank, a banner says "press any key to wake it" — do that. See [when a connection stalls](https://bambouville.com/docs/connections/#when-a-connection-stalls). ## tmux didn't pick up my changes Environment variables and startup snippets only run when the tmux session starts. Kill the session on the server (`tmux kill-session`) and reconnect. ## The files panel says the host key isn't trusted The files bridge is a separate SSH connection with the same trust rules. Open a terminal session to the host, review the [Unknown Host sheet](https://bambouville.com/docs/host-keys/#first-connection), and accept the key — then reopen the panel. ## The files panel doesn't follow my shell Directory following needs OSC 7 from your shell. Use the panel's **Enable follow — install shell integration** button, then `exec $SHELL` or reconnect. Details in [files](https://bambouville.com/docs/files/#following-your-shell). ## Sessions to a WSL host freeze mid-output The connection is fine but large bursts of output never arrive — an MTU mismatch on WSL2's virtual adapter, swallowing every big packet. See [WSL MTU stalls](https://bambouville.com/docs/wsl-mtu/). ## Local network connections fail iOS gates LAN access behind the **Local Network** permission. If you denied it, re-enable it in the Settings app under Tessera. The same permission is what lets [nearby setup](https://bambouville.com/docs/nearby-setup/) find your other device. ## Nearby setup finds no devices Both devices must have Tessera open **on the setup screen**, in the foreground, on the same network, with the Local Network permission granted on both. A version mismatch stops with an explicit "update Tessera on …" message. See [nearby setup](https://bambouville.com/docs/nearby-setup/#before-you-start). ## Handoff doesn't appear on the other device Handoff is Apple plumbing: same Apple Account on both devices, Bluetooth and Wi-Fi on, and Handoff enabled in the iOS Settings app. A locked device stops broadcasting on purpose. Take-back for shared tmux sessions also needs **tmux 3.2+** on the server. See [continuity](https://bambouville.com/docs/continuity/). ## An agent card says "status unavailable" Discovery found the agent, but precise state needs the per-host status hook — install or update it from the card. On Codex, the first integrated launch may also ask you to trust the hook via `/hooks`. See [agent center](https://bambouville.com/docs/agent-center/#how-detection-works). ## Notifications don't arrive Check the iOS notification permission (the bell settings sheet deep-links to it). Remember that background delivery is best-effort: iOS may suspend long background sessions. See [notifications](https://bambouville.com/docs/notifications/). ## A purchase didn't carry over **settings → unlimited hosts → restore purchases** re-checks your Apple Account — covering reinstalls, new devices, and the unlock included with an original paid-app purchase. See [free & unlimited hosts](https://bambouville.com/docs/unlimited-hosts/). ## Something else **settings → diagnostics → send to developer** opens a pre-addressed mail with the diagnostics log attached — you see everything before tapping send. (It needs a mail account on the device; without one, use **export log** and send the file from any mail app.) Or file an issue at [GitHub Issues](https://github.com/bambouville/tessera/issues). The log is redacted and only leaves your device when you send it.