SSH "Exit Status 255": What It Means and How to Find the Real Error
SSH error 255 means ssh itself failed to connect, verify the host or log in. Find the real cause with ssh -v and fix it, including in CI and VS Code.
SSH exit status 255 means ssh itself failed, before or while running your command. The OpenSSH manual puts it in one line: ssh "exits with the exit status of the remote command or with 255 if an error occurred." So 255 almost always means it couldn't connect, couldn't verify the server, or couldn't log you in, and the real reason is in the line ssh printed just before exiting.
Checked against the OpenBSD manual pages for ssh(1), ssh_config(5) and ssh-keygen(1), and the OpenSSH source, in November 2026.
Where you see "255"
You rarely see the number from ssh directly. It usually arrives through something that ran ssh for you:
- Your shell:
echo $?prints255after a failedsshcommand. - GitHub Actions and other CI: a deploy step fails with
Error: Process completed with exit code 255. - rsync, scp, Ansible and deploy scripts: they report that the ssh process exited with 255.
- Git over SSH: ends with
fatal: Could not read from remote repository. - VS Code Remote-SSH: the connection fails and the Remote-SSH output log shows the ssh process exiting with an error.
The wrapper's message is generic. The useful line is ssh's own error, which the wrapper may have printed further up the log or swallowed entirely.
Step 1: run the same ssh command yourself, verbosely
Run ssh by hand, as the same user, with the same host and key the failing tool uses, and add -v:
ssh -v deploy@203.0.113.10 true
echo $?
true is a remote command that does nothing and succeeds, so any 255 you get now is ssh's fault, not your script's. -v makes ssh print "debugging messages about its progress"; you can use -vv or -vvv for more. Read the last few lines before it exits. They'll match one of the cases below.
If the tool connects through a Host alias in ~/.ssh/config, use the alias. ssh -G alias prints the configuration ssh actually ends up using (hostname, port, user, identity files), which catches typos in the config file quickly. (The SSH Config File Explained covers that file.)
The common causes
| What ssh prints | What it means | First thing to check |
|---|---|---|
ssh: Could not resolve hostname myserver: Name or service not known |
The name didn't turn into an IP address | Typo, missing DNS record, or a Host alias that isn't in this machine's config |
ssh: connect to host 203.0.113.10 port 22: Connection refused |
The machine answered, but nothing is listening on that port | sshd not running, or SSH is on another port (-p 2222) |
ssh: connect to host 203.0.113.10 port 22: Connection timed out |
No answer at all | Firewall or cloud security group, wrong IP, server down |
ssh: connect to host 203.0.113.10 port 22: No route to host |
Your network couldn't reach that address | Wrong IP or network, server down, a firewall rejecting you |
kex_exchange_identification: Connection closed by remote host |
TCP connected, then the server hung up before the SSH handshake | Server-side blocking or limits; check from the provider's console |
Host key verification failed. |
ssh couldn't confirm the server is the one it knows | Missing or changed entry in known_hosts |
deploy@203.0.113.10: Permission denied (publickey). |
The server rejected every key ssh offered | Wrong key, wrong user, key not in authorized_keys |
On macOS the wording differs slightly (for example Operation timed out instead of Connection timed out), but the meaning is the same.
Can't connect: refused, timed out, no route
These happen before SSH even starts talking, so they're network problems, not key problems.
- Refused is the most useful of the three, because it proves the server is reachable. Either the SSH service isn't running, or it listens on a different port. If your provider changed the port, connect with
ssh -p 2222 user@hostor setPortin your SSH config. (ERR_CONNECTION_REFUSED explains the same idea for web servers.) - Timed out usually means packets are being dropped: a firewall rule, a cloud security group that doesn't allow port 22 from your IP, a wrong IP address, or a server that's off. Check the IP in your provider's dashboard and the inbound rules for port 22.
- No route to host points at the network path or the address itself. Double-check the IP, and whether you need a VPN to reach it.
In scripts, add a connection timeout so a dead server fails fast instead of hanging. The ConnectTimeout option covers both the TCP connection and the initial SSH handshake:
ssh -o ConnectTimeout=10 deploy@203.0.113.10 true
Host key verification failed
The first time you connect to a server, ssh asks you to confirm its fingerprint and stores it in ~/.ssh/known_hosts. Two situations fail:
- No one is there to answer the question. In CI, cron or any non-interactive run, ssh can't ask "Are you sure you want to continue connecting?", so it stops with
Host key verification failed. - The key changed. ssh prints a large
WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!banner and refuses. That's expected if you rebuilt or reinstalled the server. If you didn't, stop and find out why before going further, since this is exactly what a man-in-the-middle attack looks like.
If you know the server was rebuilt, remove the old entry and connect once interactively so you can check the new fingerprint against your provider's console:
ssh-keygen -R 203.0.113.10
ssh deploy@203.0.113.10
ssh-keygen -R "removes all keys belonging to the specified hostname" from your known_hosts file, and works even when the file stores hostnames hashed.
Permission denied (publickey)
ssh reached the server and the server said no to every key you offered. The -v output lists each key ssh tried (Offering public key: ...). Check that you're using the right username, the right key file (-i ~/.ssh/deploy_key), and that the matching public key is in that user's ~/.ssh/authorized_keys on the server. The full walkthrough is in "Permission Denied (publickey)" on GitHub; the same steps apply to your own servers.
When 255 came from the remote command
There's one exception to "255 means ssh failed": if the command you ran on the server exits with 255 itself, ssh passes that through. To tell the two apart, look at the -v output:
Authenticated to 203.0.113.10 ([203.0.113.10]:22) using "publickey".
...
debug1: Exit status 255
If you see Authenticated to followed by debug1: Exit status 255, ssh did its job. The connection and login worked, and your remote script or program is what returned 255. Debug that command on the server directly.
Making ssh reliable in CI
Most 255s in GitHub Actions and similar pipelines come from the runner being a fresh machine with no known_hosts file and no one to answer prompts. Three habits help:
- Pin the server's host key. Store the server's
known_hostsline as a secret and write it to~/.ssh/known_hostsbefore connecting. Deploy to a VPS With GitHub Actions shows the full workflow. - Use
-o BatchMode=yes. It disables password prompts and host key questions, which ssh_config(5) describes as useful "in scripts and other batch jobs." A misconfigured job then fails immediately with a clear message instead of hanging. - Don't switch off host key checking.
StrictHostKeyChecking=nomakes the error go away by trusting any server. If you must accept a key automatically,StrictHostKeyChecking=accept-newadds new hosts but still refuses a host whose key has changed. Pinning is better.
VS Code Remote-SSH
Remote-SSH needs an OpenSSH-compatible client installed on your machine and connects through it, so the fixes are the same. Open a terminal on the same machine and run ssh -v your-host-alias with the alias from VS Code's host list. Whatever error that prints is the one VS Code hit. Once plain ssh works from the terminal, Remote-SSH usually works too. (VS Code Remote SSH covers the setup.)
Quick checklist
- Run
ssh -v user@host true; echo $?by hand with the same key and alias. - Read the last lines before exit and match them to the table.
- Network errors: check IP, port, firewall and whether the server is up.
- Host key errors: verify the fingerprint, then
ssh-keygen -R hostif the server was rebuilt. - Publickey errors: check user, key file and
authorized_keys. - In CI: pin
known_hosts, addBatchMode=yesandConnectTimeout.
EasySpawn gives you a managed, always-on server you reach over SSH or from a browser, kept patched and backed up for you. Your own keys and SSH config still matter, so this guide still applies, and the browser terminal is a fallback when your local ssh setup is the thing that's broken. It's pre-launch; join the waitlist if you'd like one.
Related: How to SSH Into a Server (Mac, Windows and Linux) · "Permission Denied (publickey)" on GitHub: How to Fix It · The SSH Config File Explained: Stop Typing Long SSH Commands · SSH Keys Explained: Set Them Up Once, Properly
Keep reading
npm "Missing script: dev" (or "start"): What It Means and How to Fix It
npm error Missing script dev means the package.json npm found has no dev script. Check the folder, list scripts with npm run, and use the right name.
npm ETARGET "No matching version found": What It Means and How to Fix It
npm error code ETARGET, No matching version found, means your registry has no such version. Check typos, unpublished versions, .npmrc scopes and cache.