Common Errors
A reference table of errors you may encounter in ZestSSH, with causes and resolutions.
Connection Errors
Section titled “Connection Errors”| Error | Cause | Resolution |
|---|---|---|
Connection refused | SSH daemon not running or wrong port | Verify sshd is running and the port is correct |
Connection timed out | Host unreachable, firewall blocking, or wrong IP | Check IP/hostname, firewall rules, and internet connectivity |
No route to host | No network path to the server | Check your network connection and server availability |
Network is unreachable | No internet or VPN routing issue | Verify internet access and VPN configuration |
Connection reset by peer | Server or network forcibly closed the connection | Check server logs, firewall rules, or try reconnecting |
Software caused connection abort | Local network stack dropped the connection | Check for VPN interference or local firewall issues |
In a connection log, a failure here stops before tcp_connect: Connected and never reaches the SSH stages. If you do see tcp_connect: Connected, the network is fine and the problem is later.
Authentication Errors
Section titled “Authentication Errors”| Error | Cause | Resolution |
|---|---|---|
Permission denied (publickey) | SSH key not authorized on the server | Check authorized_keys, file permissions, and correct identity |
Permission denied (password) | Wrong password or password auth disabled | Verify password or switch to key authentication |
Too many authentication failures | Too many keys tried before the right one | Assign a specific identity to the connection |
All configured authentication methods failed | No auth method succeeded | Check identity configuration, verify credentials |
Authentication timed out | Server took too long to respond to auth | Server may be overloaded; increase timeout or try later |
In a connection log, an auth failure appears as debug: SSHClient._authWithPublicKey then debug: SSHClient._handleUserauthFailure, ending in error: Auth failed - Eub(All authentication methods failed). See Reading Connection Logs to find which stage actually failed.
Host Key Errors
Section titled “Host Key Errors”| Error | Cause | Resolution |
|---|---|---|
Host key verification failed | Server key changed since last connection | Verify the change is legitimate, then accept or reject |
Host key has changed | Server key differs from stored known_hosts entry | Investigate (could be server reinstall or MITM attack) |
No matching host key type found | Server offers only unsupported key types | Update the server’s SSH configuration to offer supported key types |
In a connection log, a changed key shows as ssh_hostkey: Host key REJECTED (instead of ssh_hostkey: Host key accepted).
Key Import Errors
Section titled “Key Import Errors”| Error | Cause | Resolution |
|---|---|---|
Wrong passphrase. Please try again. | Incorrect passphrase for encrypted key | Re-enter the correct passphrase |
This key format is not supported. | Unsupported key type (e.g. DSA) or format | Use Ed25519 or RSA keys; convert format if needed |
Invalid key file format. | File is not a valid SSH private key | Check file contents, ensure it is a private key (not public) |
No valid SSH keys found in this file. | File parsed but contained no usable keys | Verify the file contains a private key with proper PEM headers |
Backup Errors
Section titled “Backup Errors”| Error | Cause | Resolution |
|---|---|---|
A password is required to encrypt the backup. | Empty password provided | Enter a password (minimum 12 characters) |
Backup password must be at least 12 characters. | Password too short | Use a longer password |
Invalid backup file format | File does not have ZEST magic bytes | Verify the file is a valid .zest backup |
Wrong password or corrupted backup | Decryption failed | Re-enter the correct backup password |
Unsupported backup version: N | Unknown backup format version | Update ZestSSH to the latest version |
Backup file is too large (max 50 MB) | File exceeds size limit | Verify the file is a legitimate backup, not corrupted/padded |
Backup file not found | File path is invalid or file was deleted | Check the file path and ensure the file exists |
Automation Errors
Section titled “Automation Errors”| Error | Cause | Resolution |
|---|---|---|
ERROR: ZestSSH Squeezed required for automation. | Free tier does not include automation | Upgrade to ZestSSH Squeezed |
Automation is disabled in ZestSSH settings. | Automation toggle is off | Enable in Settings > Automation |
Invalid or missing automation API key. | Key is wrong, expired, or not provided | Check API key, create a new one if needed |
Connection not found: [name] | No connection matches the provided label/ID | Verify the connection label or UUID |
Snippet not found: [name] | No snippet matches the provided name | Check snippet name (case-insensitive exact match) |
Workflow not found: [name] | No workflow matches the provided name/ID | Check workflow name or UUID |
No command specified. | The execute action was called without a command | Add the command parameter |
Timeout: TCP connect timed out | Could not reach the server within the timeout | Increase timeout or check server availability |
Timeout: Authentication timed out | Auth took too long | Check credentials, increase timeout |
Timeout: Command execution timed out | Command ran longer than the timeout | Increase the timeout parameter |
Timeout: Output collection timed out | Command produced output beyond the timeout | Increase timeout or reduce output volume |
Deep Link Errors
Section titled “Deep Link Errors”| Error | Cause | Resolution |
|---|---|---|
| Deep link rejected: oversize | URI exceeds 2048 bytes | Shorten the URL (use snippets for long commands) |
| Deep link rejected: oversize query param | A single parameter exceeds 256 characters | Use snippets or shorter parameter values |
| Deep link rejected: invalid host format | Host contains control characters or spaces | Fix the host parameter |
| Deep link rejected: invalid port | Port is not 1-65535 | Use a valid port number |
Terminal Errors
Section titled “Terminal Errors”| Error | Cause | Resolution |
|---|---|---|
| Garbled/corrupted display | Terminal type mismatch or encoding issue | Set TERM=xterm-256color on the server; check locale settings |
| Colors not displaying | Server or application not using 256-color escape codes | Verify TERM is set to xterm-256color |
Backspace sends ^H instead of deleting | Terminal key mapping mismatch | Check server’s stty erase setting |
Arrow keys print ^[[A etc. | Application not reading escape sequences | Ensure the application supports xterm key sequences |
Sync Errors
Section titled “Sync Errors”| Error | Cause | Resolution |
|---|---|---|
Wrong passphrase (sync) | Sync passphrase incorrect | Re-enter the correct passphrase |
Decryption failed | Data corrupted or wrong key | Try re-entering passphrase; if persistent, reset sync |
| WebDAV 401/403 | Authentication failed | Verify WebDAV credentials |
| WebDAV timeout | Server unreachable | Check server availability and network connection |
The app keeps closing right after I open it (crash on launch)
Section titled “The app keeps closing right after I open it (crash on launch)”If ZestSSH opens and then closes, or shows an error screen instead of the home screen, work through the three steps below in order: check for the Database Error screen (Retry, never Reset first), update to the latest version, then report it with the details from the screen.
Step 1: the Database Error screen (Retry first, never Reset)
Section titled “Step 1: the Database Error screen (Retry first, never Reset)”ZestSSH keeps everything in an encrypted SQLite database. When that database cannot be opened at startup, ZestSSH shows a Database Error screen instead of closing, with the message “ZestSSH couldn’t open its database. This usually means another copy of ZestSSH is still running, or the app was just updated or downgraded.” It offers Retry, and below it a quieter Reset Database.
- Press Retry first, after closing any other ZestSSH windows.
- On Windows, a ZestSSH process that did not exit cleanly can still hold the database open with no window showing. Open Task Manager, end every
zestssh.exeprocess, then open the app again. - Never start with Reset. Reset permanently deletes every saved connection, identity, snippet and setting on this device (it asks you to confirm with Delete everything). Use it only when Retry keeps failing, and only if you have a
.zestbackup or Cloud Sync to restore from afterwards. - Technical details on that screen expands the underlying error and the database path. Copy that text into your report.
If the failure happened while the app was upgrading its database after an update, you see a migration error screen instead. ZestSSH restores its pre-update database backup automatically where it can and tells you whether that worked; the screen offers Continue, a copy-details action and Contact Support, which drafts an email to [email protected] with the details filled in.
Step 2: update to the latest version
Section titled “Step 2: update to the latest version”A launch problem that a newer release fixed is the most common outcome. Desktop builds are on the download page at zestssh.com; the desktop apps also check for a newer version and show a banner when one is available (see Installation, “Updates and the update check”). Android updates through Google Play and iOS through the App Store. Your installed version is shown in Settings > About.
Step 3: report it
Section titled “Step 3: report it”If the app reaches the home screen, open the in-app Help panel and use Report a bug. If it never does, email [email protected] with your platform, the app version (the installer file name is enough), what you see, and the Technical details text from the error screen if there is one. ZestSSH collects no telemetry, so nothing about a crash reaches us unless you send it.