SSH connection failure: distinguish network, port, authentication, and host key issues
The SSH error text points to different layers. Read it first, rather than changing authentication before the route and listener are known-good.
Maintained by Kevin · Ovalk
Scope and prerequisites
OpenSSH client/server, usually on Linux. Service names, configuration paths and available console access vary by host.
Keep an existing session and confirm independent console access before changing sshd or firewall rules. Redact verbose output before sharing: it can reveal account names and internal host details.
Common symptoms
- Connection refused, timed out, or Permission denied appears.
- Deployment automation suddenly cannot log in.
- A host key change breaks CI.
1. Classify the failure message
Refused generally means the target is reachable but nothing accepts the port. A timeout more often indicates routing or filtering. Permission denied is the point to inspect users, keys, and sshd policy.
ssh -vvv user@example.com
nc -vz example.com 222. Use a safe out-of-band path
From a console or a same-network jump host, inspect the listener, firewall, and recent configuration change. Keep a working session open while validating sshd configuration changes.
ss -lntp | grep :22
sshd -t
journalctl -u sshd --since "1 hour ago" --no-pager3. Verify host-key changes out of band
A key change can be legitimate after rebuild or failover, but it can also indicate interception. Verify the fingerprint against a trusted console or inventory before updating automation.
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
ssh-keygen -F example.comInterpret the evidence
| Observation | What to check next |
|---|---|
| Connection refused | Verify listener and destination port; a firewall or intermediary can actively reject the attempt. This is not an authentication error. |
| Permission denied (publickey) | Inspect which key the client offered, the intended user and server logs. Do not enable password login just to bypass diagnosis. |
| REMOTE HOST IDENTIFICATION HAS CHANGED | Stop and verify the fingerprint independently. Never delete known_hosts entries simply because the warning blocks access. |
Illustrative diagnosis
A hypothetical example to explain the reasoning, not a reported customer incident or a claim of testing on your stack.
Automation fails with Permission denied immediately after a key rotation, but TCP connects and the host fingerprint is unchanged. Focus on the automation account, offered key and server authorization. Opening more firewall ports would not help an authentication failure. Verify the new public key and account policy through the trusted console.
Verify recovery
- Open a second independent session using the intended user and authentication method before closing the recovery session.
- Test the actual deployment or automation connection and confirm the trusted host-key check remains enabled.
Rollback and stopping point
Back up the changed server configuration and validate with sshd -t before reload. If a new session fails, restore the previous configuration from the still-open session or console. Never weaken host-key checking as a rollback.
Prevention and long-term repair
- Maintain console access and a tested break-glass process.
- Audit security group, sshd, and authorized-key changes.
- Keep verified host-key inventories for automation.
References and corrections
Use the documentation for your installed version. The references below explain the underlying behavior; commands still need environment-specific validation.
Report a correction to Kevin — include the page URL, version and a redacted reproduction. See our editorial policy.