Comprehensive guide to identifying and troubleshooting SSH issues

SSH (Secure Shell) is one of the most important tools for anyone managing servers. Whether you’re accessing a cloud instance, updating software on a remote machine, copying log files from a production instance, or running automated scripts, SSH is what makes it all possible.

Given how central SSH is to everyday server operations, even small issues can quickly become blockers. That’s why it’s important to know how to spot problems early and fix them quickly. This guide goes over the most common SSH issues and shares step-by-step advice to troubleshoot and fix them.

A Quick overview of SSH

SSH is a protocol that lets you connect securely to remote systems over a network. It works by creating an encrypted connection between the client (your local machine) and the server.

This encryption keeps your data safe from eavesdropping or tampering. Authentication usually happens using a username and password, or more securely, with SSH key pairs. Once connected, you can run shell commands on the server just like you would on a local machine.

Why is quick troubleshooting of SSH issues important?

Before we look at the most common SSH issues, let’s explore why troubleshooting them quickly is important:

• SSH is often the only way to access headless or remote systems, so any delay can block critical work.
• Delayed fixes can lead to longer outages, especially during deployments or emergencies.
• Slow response to SSH problems can lock out multiple team members and stall collaboration.
• If an SSH issue is caused by a security misconfiguration, waiting too long to address it can expose systems to risk.
• Automated jobs or scripts that rely on SSH may silently fail or cause a chain reaction of errors if the issue isn’t fixed quickly.
• In cloud environments, instances may be short-lived or auto-scaled. Missing the window to fix SSH access can result in lost logs or debugging info.

Authentication failures

Authentication failures are among the most frustrating SSH problems because they can feel like a dead end. This section covers a few common reasons why authentication might fail and how to fix each.

Wrong username or host configuration

Even with the right key or password, using the wrong username or connecting to the wrong host will cause the connection to fail.

Symptoms

• “Permission denied” error immediately after trying to connect
• SSH prompts for a password even though key-based auth is set up

Troubleshooting

• Double-check the full SSH command you’re using. Make sure the username and hostname are correct. For example, use ssh user@example.com, not just ssh example.com.
• If using an SSH config file (~/.ssh/config), verify that the correct User and HostName values are defined under the correct Host entry.
• Confirm that the remote server allows SSH access for the username you’re using. Some usernames (like root) may be blocked by the server config.
• If the username is correct but access is still denied, try creating a temporary user on the server (if you have access) to test whether the issue is specific to your account.

Missing or incorrect SSH key

If the private key is missing, not loaded, or doesn’t match the public key on the server, authentication will fail.

Symptoms

• SSH connection asks for a password instead of using the key
• “Permission denied (publickey)” error shows in terminal

Troubleshooting

• Run ssh -v user@host to see if your key is being offered and whether the server accepts it. This can help narrow down the cause.
• Make sure the private key file exists on your local machine, has the correct permissions, and is referenced correctly in your SSH config or command.
• Check that the corresponding public key is present in ~/.ssh/authorized_keys on the server for the right user account.
• If using an SSH agent, confirm that the key is loaded using ssh-add -l. If it’s missing, run ssh-add /path/to/key.
• Review the server’s sshd_config file to ensure that PubkeyAuthentication is set to yes and AuthorizedKeysFile is properly configured.

Password authentication disabled

You may face issues while logging into a server using a password and username.

Symptoms

• “Permission denied (password)” error even when typing the correct password
• Login works with key-based auth but not with password

Troubleshooting

• On the server, open /etc/ssh/sshd_config and check if PasswordAuthentication is set to no. If you want to allow passwords, change it to yes and restart the SSH service.
• If the setting is already correct, verify that no other config option (like UsePAM) is blocking password login.
• Make sure the password hasn’t expired or been locked out due to too many failed attempts. You can check account status using passwd -S username or chage -l username.
• Some environments like cloud-hosted instances disable password login by default. Check the provider’s documentation for allowed authentication methods.

File permission issues

SSH is strict about file permissions for security reasons. If your .ssh directory or key files have incorrect permissions, access will be blocked.

Symptoms

• “Permission denied (publickey)” or “Authentication failed” errors despite correct keys
• SSH server logs show errors related to "bad permissions"

Troubleshooting

• Set permissions on your local private key to 600 using chmod 600 ~/.ssh/id_rsa and ensure .ssh itself is 700.
• Make sure the home directory of the remote user isn’t world-writable, as this can also cause SSH to reject the connection.
• Use ls -ld and ls -l to inspect permissions and ownership of all relevant files and directories. Fix ownership with chown user:user ~/.ssh if needed.

Connection timeouts

Connection timeouts happen when your SSH client can’t establish a connection to the remote server within a certain time. Let’s explore such issues further in this section.

Firewall blocking port 22

SSH usually runs on port 22. If that port is blocked on either side of the connection, it won’t go through and the connection will time out.

Symptoms

• Connection hangs with no response and eventually times out
• Cannot telnet or curl the server on port 22

Troubleshooting

• Try running telnet your-server.com 22 or nc -vz your-server.com 22 to check if the port is reachable.
• On the server, check firewall rules using the ufw status, iptables -L, or firewalld commands to confirm port 22 is open.
• On the client side, make sure your own firewall or antivirus software isn’t blocking outbound connections on port 22.
• If you're behind a corporate or hotel network, it may be filtering outbound SSH. Try switching networks or using a VPN.
• If the server uses a non-standard SSH port, make sure you specify it using the -p flag in your SSH command.

SSH service not running on server

If the SSH daemon is down, you won’t be able to connect no matter what you do from the client side.

Symptoms

• Immediate timeout or "Connection refused" error
• Server is reachable via ping, or through other ports, but SSH doesn’t respond

Troubleshooting

• Use another method to access the server, such as a cloud provider's web console or KVM, and check if sshd is running by using systemctl status ssh or service ssh status.
• If it’s not running, restart the service using systemctl start ssh or service ssh start, depending on the distro you are on.
• Make sure the SSH service is set to start on boot so it doesn’t go down after a reboot.
• Check the logs in /var/log/auth.log, /var/log/secure, or journalctl -u ssh for any crash or startup failure messages.

Network routing or VPN issues

If there’s a problem with routing between the client and the server, packets won’t reach the destination.

Symptoms

• SSH client shows a long delay before failing to connect
• Pings fail or show very high latency

Troubleshooting

• Use traceroute (or tracert on Windows) to see where the connection is failing between you and the server.
• If you’re using a VPN, try disconnecting or switching VPN servers. Some VPNs block or reroute traffic in ways that affect SSH.
• Check if the server has any routing issues or misconfigured gateways. Run ip route or netstat -rn on the server side.
• If you recently changed network settings on the server, especially involving firewalls or interfaces, review those changes to make sure SSH traffic is still allowed.

SSH key issues

SSH keys are widely used because they’re more secure than passwords and support automation. But they can still cause connection problems if there’s something wrong with how they’re created, stored, or used. Below are some common SSH key issues and how to troubleshoot them.

Key format not supported

Some newer key formats may not be supported by older SSH clients or server configurations.

Symptoms

• SSH client errors mentioning "invalid format" or "unsupported key type"
• SSH fails silently when trying to use the key

Troubleshooting

• Check the key type with ssh-keygen -lf your-key-file.
• If the key was created using a newer OpenSSH version, try creating a compatible RSA key using ssh-keygen -t rsa -b 4096 as a fallback.
• On the server, make sure the SSH daemon supports the key type by checking its version using sshd -v.
• If using a hardware-backed key (like YubiKey or a FIDO2 device), confirm the server is configured to accept these key types and has the right modules installed.

Wrong file format or corrupted key

SSH keys need to be in the correct format. If a key was copied incorrectly or corrupted, the SSH client won’t be able to use it.

Symptoms

• “Load key... invalid format” or “not a valid private key file” error
• SSH skips the key silently and tries password instead

Troubleshooting

• Open the private key in a text editor and make sure it starts with -----BEGIN OPENSSH PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY----- depending on the type.
• Avoid copying keys over chat apps or email, as formatting may get altered. Use scp or paste via terminal session if needed.
• Recreate the key using ssh-keygen if it’s been damaged or improperly exported. Keep a backup of known working keys.
• Make sure you're not accidentally using the public key as the private key. Public keys typically end with .pub and are not usable in ssh commands.

Using the wrong key in multi-key environments

If you have many keys on your system or loaded into your SSH agent, the client may try the wrong one first.

Symptoms

• SSH takes a long time to fail or hangs before showing a denial
• Verbose output shows many key attempts before rejection

Troubleshooting

• Use ssh -v user@host to check which keys the client is trying. The debug output will show each key attempt.
• Create a specific Host entry in your ~/.ssh/config file with an explicit IdentityFile line pointing to the correct key.
• If using ssh-agent, clear out extra keys with ssh-add -D and add only the one you need using ssh-add /path/to/key.
• Add the IdentitiesOnly yes option in your SSH config or command line to force the client to use only the specified key.

Performance issues

Sometimes SSH connects without errors, but the session feels slow or unresponsive. This can happen due to a performance bottleneck or a network misconfiguration. Let’s explore more below.

DNS resolution delays

SSH servers may try to resolve the client’s hostname or IP, which can cause delays if DNS is misconfigured or slow.

Symptoms

• Long delay before the login banner or password prompt appears
• SSH connects eventually, but with a noticeable pause

Troubleshooting

• Check if the delay happens only on the first connection. If so, reverse DNS lookups may be the cause.
• On the server, edit /etc/ssh/sshd_config and set UseDNS no to disable reverse lookups. Restart SSH after the change.
• Test DNS resolution using the dig, nslookup, or host commands on both client and server to identify slow responses.
• If using a custom DNS setup, make sure your resolvers are reachable and fast. Consider switching to faster public DNS servers if needed.

High network latency or packet loss

Slow or unreliable network paths can make even basic SSH commands feel sluggish.

Symptoms

• You notice a lag while typing
• File transfers with scp or rsync take unusually long

Troubleshooting

• Run ping or mtr from client to server to check for latency or dropped packets. High latency or jitter can cause noticeable delays.
• If on Wi-Fi, switch to a wired connection and test again. Wireless networks can cause unpredictable lag.
• Use scp -l to limit bandwidth during file transfers, which may reduce dropped packets on overloaded links.
• If you’re accessing servers over the internet, try running through a VPN or bastion host closer to the destination region.

Encryption overhead on low-end devices

Older or resource-constrained devices may struggle to handle SSH encryption, especially with stronger algorithms.

Symptoms

• SSH session becomes unresponsive during high-load operations
• CPU usage spikes on the client or server when running SSH commands

Troubleshooting

• Check CPU usage during the SSH session using top or htop to confirm encryption is causing high load.
• Use a more efficient cipher for the session, such as ssh -c aes128-ctr user@host. This can reduce CPU load at the cost of slightly weaker encryption.
• On the server, avoid forcing strong but CPU-heavy algorithms unless necessary for your security needs.
• If using older embedded systems or Raspberry Pi devices, consider upgrading to newer hardware or reducing SSH usage during high-load periods.

Best practices for SSH security

Finally, here are some best practices you can follow to avoid many of the aforementioned issues, and make your day-to-day work more predictable.

• Use SSH key-based authentication instead of passwords whenever possible. It’s more secure and easier to manage across multiple servers.
• Keep your keys safe and organized. Don’t reuse the same key across environments without tracking where it’s being used. Store private keys in secure locations and use ssh-agent to avoid repeated passphrase prompts.
• Harden your SSH server configuration. Disable root login, use non-standard ports if needed, and limit access to specific users or IP addresses.
• Enable logging and review your logs regularly. SSH logs can quickly reveal repeated brute-force attempts or unexpected login activity.
• Automate where it makes sense. For example, if you manage network equipment or servers at scale, tools like Site24x7 offer credential management features that can help. You can securely store SSH, Telnet, or SNMP credentials and use them to automate configuration backups across devices.
• Use connection keep-alives and timeout settings to avoid hanging sessions, especially if you're working over unstable networks or VPNs.
• Just like passwords, SSH keys should be changed on a schedule to reduce long-term risk if a private key is ever leaked or misused.
• Integrate tools like Duo or Google Authenticator with PAM to add a second layer of verification beyond the SSH key or password.
• Instead of opening SSH access to every server, route traffic through a single, tightly-controlled entry point. This makes monitoring and securing access much easier.
• In your SSH server config, remove support for older versions like SSHv1 and weak ciphers such as arcfour or cbc-based algorithms.
• Send your SSH access logs to a SIEM or log server for better visibility and correlation across your infrastructure.

Conclusion

SSH is a mission-critical service, and any issues with it should be addressed quickly to avoid downtime, delays, or security risks. We hope this guide helps make your next troubleshooting session easier and more effective.