SSH Connection Troubleshooting

Diagnose cloud GPU SSH failures with key, port, host, firewall, and instance-state checks.

By Hostnot GPU · 9/6/2026

Work through SSH failures in order: allocation state, destination, network connection, server identity, then account authentication. The first error is usually more useful than repeated retries. Keep one known-good session open while diagnosing a second connection.

Establish the expected endpoint

Confirm the instance is ready in the authenticated workspace and copy its current host, assigned port, username, and fingerprint. A replacement can change these values. Check ssh -V locally and confirm the matching private key exists. These commands use a Linux/macOS/WSL shell and intentionally non-working placeholders:

GPU_HOST='replace-with-assigned-host'
GPU_PORT='replace-with-assigned-port'
GPU_USER='replace-with-assigned-user'
KEY="$HOME/.ssh/hostnotgpu_ed25519"
ssh -G -i "$KEY" -p "$GPU_PORT" "$GPU_USER@$GPU_HOST"
ssh -vvv -o ConnectTimeout=15 -o IdentitiesOnly=yes -o StrictHostKeyChecking=ask -i "$KEY" -p "$GPU_PORT" "$GPU_USER@$GPU_HOST"

ssh -G prints effective client configuration without opening a connection. Inspect host, port, user, identity files, and any proxy/jump settings that may redirect traffic. Verbose connection output includes hostnames, usernames, and local paths; redact it before sharing. It should never be accompanied by your private key.

Resolve network failures first

Could not resolve hostname: check copied spelling and local DNS/network state. Authentication has not started.
Connection timed out: compare instance readiness and exact assigned port; check your local firewall, VPN, and outbound network policy. An approved alternate network can isolate a local restriction. Failed ping is inconclusive because ICMP may be blocked.
Connection refused: a reachable endpoint rejected the TCP connection. The route, port, provisioning state, or SSH service may be wrong.
Connection reset during handshake: preserve timing and verbose output; a gateway, policy, or starting service may have closed it. Stop rapid retry loops and consult support.

Do not scan neighboring assigned ports or disable remote firewalls as an exploratory step. A single correct-endpoint attempt is enough to gather initial evidence.

Handle host-key warnings as identity failures

For a changed fingerprint, stop. Confirm replacement or legitimate key rotation through the authenticated workspace/support and compare the exact algorithm and SHA256 fingerprint. The client key you uploaded is unrelated to this server-identity check. An untrusted network key scan cannot prove legitimacy.

For a non-default assigned port, the known-hosts lookup is usually bracketed. Inspect the specific entry first:

ssh-keygen -F "[$GPU_HOST]:$GPU_PORT"

Only after independently verifying a legitimate replacement, remove that stale endpoint entry with ssh-keygen -R "[$GPU_HOST]:$GPU_PORT", reconnect, and compare the replacement fingerprint before acceptance. For default port 22 the entry may use the bare hostname. Never delete the entire known-hosts file or globally disable checking.

Fix authentication without weakening it

Permission denied (publickey): verify username and which public key was provisioned. ssh-keygen -lf ~/.ssh/hostnotgpu_ed25519.pub -E sha256 identifies your registered public key.
Too many authentication failures: a client agent may offer unrelated keys before the right one. Use the explicit identity and IdentitiesOnly=yes; inspect inherited identity configuration if it persists.
Unprotected private key file: on Unix, check ownership and set that private file to mode 600. Native Windows requires appropriate ACLs instead.
Invalid key format: check that the selected file is the private key, not a damaged copy, public key, or unsupported exported format. Do not paste it into an online validator.

Escalate with actionable evidence

Provide instance identifier through private support, timestamps, current state, exact error, client version, and whether an approved alternate network behaves differently. Key additions may not propagate to existing hosts; use the supported recovery path if locked out. Bound troubleshooting time on an idle rented allocation and reconcile any still-running job before replacement. Continue with key rotation or the successful connection checklist.