Common Errors

A reference table of errors you may encounter in ZestSSH, with causes and resolutions.

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

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

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

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

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

Error	Cause	Resolution
ZestSSH Pro subscription required for automation.	Free tier does not include automation	Upgrade to ZestSSH Pro
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

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

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

Error	Cause	Resolution
Wrong passphrase (Cloud 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