Troubleshooting 📱 Mobile

Common problems, with the actual fix instead of "uninstall and reinstall."

This guide describes the mobile (Android) client. Desktop reproductions and the --debug flag are covered in Desktop Troubleshooting.

🚫 "Connection refused" / "Connection timed out"

Check the host and port are right. SSH defaults to 22; some servers run on 2222 or other custom ports.
Try the host from a desktop (ssh user@host). If that also fails, the issue is server-side or network — not TabSSH.
If you're on cellular, your carrier may block port 22. Try a different port or use a jump host on a non-blocked port.
Some corporate / hotel WiFi blocks SSH outright. Same workaround.
If the server is behind a NAT, port forwarding on the router needs to map external port → SSH port.

Confirm the username matches what the server expects (root, your user, etc.).
For password auth: typo? Caps lock? Saved password gone stale because you changed it server-side?
For key auth: is the right key selected on the connection? Is its public key actually in ~/.ssh/authorized_keys on the server, with correct permissions (700 on ~/.ssh, 600 on authorized_keys)?
If the key is passphrase-protected, you'll be prompted at connect time — make sure you typed the passphrase right.
Tap Copy error in the failure dialog to grab the SSH error string and search it.

This is the MITM warning. It means the server's host key is not the one TabSSH stored last time.
Most common benign cause: the server was reinstalled, or its SSH host keys were rotated. Verify with the admin.
If you confirm it's legitimate: tap the warning → select the option to remove the old key from the trust store, then reconnect and accept the new fingerprint.
Do NOT click through this warning blindly, especially on hostile networks.

Enable Compression in the connection's Advanced Settings — significant on flaky cellular.
Increase Keep-alive interval if connections are dropping when idle.
Use Mosh if the network is genuinely bad — it's designed for high-latency / lossy links and survives roaming.
Set scrollback buffer lower if scrolling feels heavy on a low-end device (Settings → Terminal).

TabSSH ships native mosh-client binaries per Android ABI in the APK — no separate install needed.
The server side must have mosh-server installed (apt install mosh on Debian/Ubuntu).
UDP ports 60000-61000 must be open on the server's firewall (configurable, but those are the defaults).
If Mosh refuses to start, check that the SSH handoff worked first — Mosh starts as an SSH login that hands off.
If the server has a non-standard $TERM, TabSSH ships fallback terminfo entries embedded in the binary.

Double-check the SAF folder is still pickable — some storage providers (Nextcloud, etc.) revoke long-running URI permissions; you may need to re-pick the folder in Settings → Sync.
If sync fails on Device B with "decryption failed", you've typed the wrong sync password — there's no recovery without it.
Sync only fires when at least one trigger is enabled (manual, on launch, on change, scheduled). Check Settings → Sync → Triggers.
WiFi-only mode won't sync on cellular — toggle off if you want to sync everywhere.
Background sync uses Android's WorkManager; battery optimisation can delay scheduled jobs by minutes to hours. Whitelist TabSSH if this matters.

Debug builds auto-enable a crash reporter and an ANR watchdog (logs main-thread freezes >5s). The crash report appears on next launch; tap "Copy" and share it.
Release builds: enable Settings → Logging → Enable Debug Logging, reproduce the issue, then menu → Copy Debug Logs.
Paste the log into a GitHub issue (issues). Include device model, Android version, and what you were doing.
Don't share password / key contents in logs — TabSSH redacts the obvious ones, but eyeball before posting.

Enable "Install from unknown sources" for your browser / file manager in Android Settings.
If upgrading: TabSSH refuses to install over a build with a different signing key. Uninstall the old APK first, then install the new one.
If the APK is corrupt, the SHA-256 checksum on the GitHub release page will mismatch — re-download.
Wrong architecture: ARM64 won't install on an ARM-only device, and vice-versa. Most modern phones are arm64-v8a; emulators are usually x86_64.