ssh and scp exit codes: 255 is ssh's own failure, anything else is the remote command's

What it is

The OpenSSH manual states it plainly: "ssh exits with the exit status of the remote command or with 255 if an error occurred." That means:

• Any value 0–254 came from the command that ran on the remote host — ssh is just relaying it.
• 255 means either ssh itself failed — DNS failure, connection refused, authentication failure, host key mismatch, a protocol-level error — or the remote command was killed by a signal, leaving no exit status to relay (a remote kill -9 shows up as 255, not 137).

scp's manual is far less specific: "The scp utility exits 0 on success, and >0 if an error occurs." It does not separate a local/transport failure from a remote one the way ssh's 255 convention does. Current OpenSSH scp (e.g. 9.6) exits 1 for file errors and 255 when the ssh connection fails, but the manual does not promise this.

Why it matters

A script that runs ssh host some-command and only checks $? -eq 0 cannot tell "the remote command failed with its own meaningful code" from "ssh never reached the host." Reacting to both the same way — for example, retrying blindly — will hammer a host that is simply refusing connections, or silently ignore a remote command's real 1/2/127 exit status.

How to apply

• After ssh host cmd, check for 255 first: treat it as a connectivity/auth/host-key problem and inspect ssh's stderr (run without -q, which suppresses these diagnostics) rather than the remote command's own error space.
• Any other non-zero code is the remote command's own contract — apply the same reasoning you would for running that command locally (e.g., 127 likely means "command not found" on the remote host's PATH, not on the local one).
• For scp, since only "0 vs >0" is documented, do not try to infer the failure class from the number; parse scp's/ssh's stderr text, or switch to sftp/rsync -e ssh if you need finer-grained, documented codes.
• When wrapping in timeout, its own codes (124, or 137 after --kill-after) sit on top of ssh's convention — check them before interpreting the rest.

Pitfalls

• A remote command that itself happens to exit 255 is indistinguishable, by exit code alone, from an ssh-level failure; disambiguate using ssh's stderr banner or by having the remote command avoid 255.
• ProxyJump/ProxyCommand failures also surface as ssh's own 255, not as a distinct code — the failure could be in the jump host, not the final target.