EC
255
BashERRORNotableExit CodeHIGH confidence

Exit status out of range / fatal error

Production Risk

Always disambiguate: was 255 an SSH connection failure or an application fatal error?

What this means

Exit code 255 has two common meanings: (1) a script used `exit -1` or a value that wraps to 255, or (2) an SSH connection failed before the remote command ran. Some tools also use 255 as a general fatal error code.

Why it happens
  1. 1Script called `exit -1` — bash wraps -1 to 255
  2. 2SSH connection failed or was refused before executing the remote command
  3. 3xargs received an exit code > 128 from a child process
  4. 4Some tools use 255 as a universal "fatal error" sentinel
How to reproduce

SSH failing to connect to a remote host.

trigger — this will error
trigger — this will error
ssh -o ConnectTimeout=3 nonexistent-host "echo hello"
echo "Exit: $?"

expected output

ssh: connect to host nonexistent-host port 22: Connection refused
Exit: 255

Fix 1

Check SSH connectivity separately

WHEN When SSH returns 255 in automation

Check SSH connectivity separately
# Distinguish SSH failure from remote command failure
ssh_out=$(ssh user@host "my_command" 2>&1)
ssh_exit=$?
if [ $ssh_exit -eq 255 ]; then
  echo "SSH connection failed: $ssh_out" >&2
elif [ $ssh_exit -ne 0 ]; then
  echo "Remote command failed with $ssh_exit" >&2
fi

Why this works

SSH returns 255 only for its own connection failures, not for the remote command exit code.

Fix 2

Use positive exit codes instead of -1

WHEN When writing scripts that use exit -1

Use positive exit codes instead of -1
# Use a positive code in range 1-254
exit 1   # general error
# NOT: exit -1  (wraps to 255, ambiguous)

Why this works

Exit codes must be 0–255; negative values wrap around, producing ambiguous exit codes.

What not to do

✕ Use exit -1 in scripts

Bash wraps it to 255, which collides with SSH connection failures and makes diagnostics harder.

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Bash errors