SSH Troubleshooting: Diagnose Connection Errors Safely

Learning objectives

• Map common errors to the network or authentication stage that produced them.
• Use safe Windows checks to test DNS and TCP reachability.
• Respond correctly to host key warnings.
• Collect useful, redacted evidence for an administrator.

Prerequisites

• The expected hostname, SSH port, username, and authentication method.
• Authorization to connect and, for server checks, authorization to administer it.
• A record of the complete error text with secrets removed.

A safe troubleshooting workflow

1. Read the exact error

   Record whether it says refused, timed out, name not known, permission denied, or host key changed. These are not interchangeable.

2. Verify inputs

   Check hostname spelling, SSH port, username, VPN requirement, and selected key. Compare with the administrator’s current instructions.

3. Test resolution and port reachability

   In PowerShell, use Resolve-DnsName host.example.net and Test-NetConnection host.example.net -Port 22. Substitute the actual port.

4. Compare scope

   Determine whether other authorized users or networks are affected. This helps locate a device, network, or server issue without changing controls.

5. Inspect logs safely

   Use PuTTY’s Event Log or ssh -v. Redact usernames, hostnames, and public IPs when appropriate. Never disclose passwords or private keys.

Connection refused vs. connection timed out

Connection refused

The destination responded but nothing accepted TCP connections on that port, or a firewall actively rejected them. Common causes are a wrong port, stopped SSH service, service listening only on another interface, or a reject rule. Recheck the port. An authorized server administrator can inspect the SSH service and listening sockets.

Connection timed out

No usable response arrived before the deadline. Common causes include a wrong IP, missing VPN or route, filtered traffic, cloud firewall/security-group rules, or an offline host. Test DNS and the exact port. A successful ping is neither required nor sufficient because ICMP and TCP can be treated differently.

Name and network errors

• Could not resolve hostname: check spelling, remove protocol prefixes such as https://, and verify the expected DNS or VPN connection.
• No route to host / network unreachable: confirm local connectivity, VPN routes, and whether a private address is reachable from your current network.
• Connection reset: a server or network device closed the connection. Compare client logs with authorized server and firewall logs.
• Intermittent failure: record time, network, and destination; check for unstable Wi-Fi, VPN reconnects, or server resource events before repeatedly retrying.

Authentication failures

Permission denied means the network and SSH protocol stages generally succeeded, but the server did not accept an offered method. Confirm the username first—keys and passwords belong to an account. Check Caps Lock and keyboard layout for passwords, but avoid repeated attempts that may lock the account.

For a key, confirm the client loaded the matching private key and the corresponding public key is authorized for that account. Server policy, ownership, file permissions, expired accounts, or unsupported algorithms may also matter. Use verbose output to see methods offered and accepted, but do not post complete logs publicly without redaction.

Host key warnings and configuration mistakes

A changed host key could follow a legitimate rebuild, migration, or key rotation. It can also indicate a wrong destination or interception. Stop and compare the new fingerprint with the server administrator through a trusted channel. Remove or replace a stored key only after verification.

Common configuration mistakes include swapping username and hostname, using a web URL rather than a hostname, confusing the SSH server’s host key with your user key, loading a PPK into OpenSSH, saving changed PuTTY settings to the wrong profile, and testing a private IP without its required network path.

When requesting guidance, include the program and version, Windows version, the command or PuTTY settings with secrets removed, the exact error, whether a VPN is expected, and what changed. Do not include a password, private key, key passphrase, recovery code, or a complete unedited log.

Continue learning