Skip to content
ZestSSH Docs

Troubleshooting Setup

This page covers the most common problems you may hit when setting up ZestSSH for the first time.

Connection fails immediately

Section titled “Connection fails immediately”

Symptoms: You tap Connect and get an error within a few seconds. The terminal never opens.

Check these first:

  1. Hostname and port are correct. A typo in the hostname or a wrong port is the most common cause. Default SSH port is 22 — if your server uses a non-standard port, make sure it matches.

  2. The server is reachable from your network. If you are on mobile data, your carrier may block outgoing connections on port 22. Try switching to Wi-Fi. If you are on a corporate network, a firewall may be blocking SSH traffic.

  3. DNS resolution works. If you are using a hostname (not an IP address), verify that it resolves. Try connecting by IP address instead to rule out DNS issues.

  4. The SSH service is running on the server. Log in to the server through another method (console, web terminal) and check:

Terminal window
systemctl status sshd

If the service is stopped, start it:

Terminal window
sudo systemctl start sshd

Key not accepted

Section titled “Key not accepted”

Symptoms: You have configured key-based authentication, but the server rejects the key and either falls back to password auth or disconnects.

Common causes:

  1. The public key is not in authorized_keys. Copy the public key from ZestSSH (Identities > [your key] > Copy Public Key) and add it to ~/.ssh/authorized_keys on the server. Make sure you copy the entire line, including the key type prefix (ssh-ed25519, ssh-rsa, etc.).

  2. File permissions are wrong. OpenSSH is strict about permissions. On the server, run:

Terminal window
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

The .ssh directory must not be writable by group or others. The authorized_keys file must not be writable by anyone except the owner.

  1. Wrong key selected. In the connection editor, verify that the correct identity is assigned. If you have multiple keys, it is easy to pick the wrong one.

  2. Server does not support the key type. Older servers (OpenSSH < 6.5) do not support Ed25519. If you generated an Ed25519 key and the server is running an old SSH version, generate an RSA-4096 key instead.

  3. The key was imported with the wrong passphrase. If the import appeared to succeed but the key data is corrupt, the server will reject it. Try re-importing the key and double-check the passphrase.

Cannot connect to LAN servers

Section titled “Cannot connect to LAN servers”

Symptoms: You can connect to internet-facing servers but not to devices on your local network (e.g., a Raspberry Pi at 192.168.1.x).

On Android:

  • Make sure you are connected to the same Wi-Fi network as the target device.
  • Some Android versions isolate apps from the local network by default. Check your Wi-Fi settings for a “Private DNS” or “Network isolation” toggle.
  • Hotspot isolation (AP isolation) on your router can block device-to-device traffic. Check your router’s settings and disable AP isolation if it is enabled.

On desktop (Windows/macOS/Linux):

  • Verify that a firewall is not blocking outgoing connections on port 22. On Windows, check Windows Defender Firewall. On macOS, check the built-in firewall in System Settings > Network.
  • If the target device is on a different subnet or VLAN, you may need a route configured.

General:

  • Try pinging the target IP from another app or the system terminal to confirm network connectivity.
  • Verify the SSH server on the target device is bound to 0.0.0.0 (all interfaces) and not 127.0.0.1 (localhost only). Check /etc/ssh/sshd_config for the ListenAddress directive.

Database error on first launch

Section titled “Database error on first launch”

Symptoms: ZestSSH shows an error screen on first launch instead of the normal onboarding wizard. The error mentions the database or SQLite.

ZestSSH uses an encrypted SQLite database (SQLCipher). If the database file cannot be created or opened, the app displays a standalone error screen with two options:

  • Retry — attempts to open the database again. This can help if the error was caused by a transient filesystem issue (e.g., storage was temporarily full).
  • Reset — deletes the database file and recreates it from scratch. This is a last resort — it erases all stored data. On first launch, there is no data to lose, so resetting is safe.

Common causes:

  1. Insufficient storage space. The database file is small (~100 KB initially) but the device needs free space to create it. Free up storage and retry.

  2. File permission issues. On Android, this can happen if the app’s data directory is on external storage with restricted permissions. Reinstalling the app usually resolves this.

  3. Corrupted app data. If ZestSSH was previously installed and uninstalled without clearing data, leftover files may conflict. Clear the app’s data in your device settings, or uninstall and reinstall.

If the error persists after trying the above, the error details screen shows the underlying exception message. Include this in any bug report.