📘 ** Exit Status Code = 255 in Bash**

---

🎯 What You Will Learn

1. Understand what exit status code = 255 means in Bash.
2. Learn how it represents abnormal termination or out-of-range exit codes.
3. Identify when Bash or other programs (SSH, rsync, etc.) return 255.
4. Differentiate between script-level errors, network/SSH failures, and restricted exit values.
5. Apply 255 handling in WordPress VPS automation, remote backups, and deployment pipelines.
6. Learn to prevent and debug exit 255 in real-world VPS contexts.

---

1. 5W + 1H Framework

Element	Description
What	Exit code 255 indicates abnormal termination — often caused by invalid exit values, failed SSH connections, permission issues, or missing targets in remote commands.
Why	Bash restricts exit codes to 0–255. If a script calls exit with a value outside that range, it wraps around or becomes 255. SSH and network tools also use 255 for unreachable hosts or authentication failures.
Who	System admins, Bash scripters, and DevOps engineers managing remote tasks (SSH, rsync, scp, WP automation).
When	When a command, SSH session, or script fails to execute properly or terminates unexpectedly.
Where	Common in cron jobs, deployment pipelines, backup transfers, and cross-server WordPress management scripts.
How	Bash and many other tools (OpenSSH, rsync, scp) internally use 255 to signal fatal errors or unreachable destinations.

---

2. Prerequisites

You should already understand:

• Exit codes and their ranges (0–255).
• SSH, rsync, and remote Bash command execution.
• Common VPS tools like scp, rsync, and ssh.
• How to use $? to inspect command return values.

---

3. Core Syntax and Examples

🧩 Definition

Exit code 255 = “Abnormal termination” — used for unreachable SSH connections, invalid exit values, or unrecoverable execution errors.

Example 1 – SSH Connection Failure

ssh root@unknown-host
echo $?

Expected Output:

ssh: Could not resolve hostname unknown-host: Name or service not known
255

Explanation: The SSH client couldn’t connect (DNS or network error). Exit 255 signals a fatal SSH failure. Use Case (WordPress VPS): Remote deployment script tries to connect to an offline backup server.

Example 2 – SSH Permission Denied

ssh [email protected]
echo $?

Expected Output:

Permission denied (publickey,password).
255

Explanation: Authentication failed. SSH client exits with code 255, signaling fatal access error. Fix:

ssh-copy-id [email protected]

---

Example 3 – Script Exiting with Invalid Code

#!/bin/bash
exit 999
echo $?

Expected Output:

255

Explanation: Exit code limit is 0–255. Anything above 255 wraps or is reported as 255 (out-of-range exit). Use Case: Bad exit control in complex WP maintenance scripts (e.g., exit $status where $status > 255).

Example 4 – rsync or scp Failure

rsync -avz /backup [email protected]:/remote/backup/
echo $?

Expected Output (if network unreachable):

ssh: connect to host 10.0.0.5 port 22: Connection timed out
255

Explanation: Remote server unreachable → rsync/ssh fails → exit 255. Use Case: Automated WordPress backup via rsync fails when remote VPS is offline.

Example 5 – Command Not Executable via SSH

ssh user@remote '/root/unknown_script.sh'
echo $?

Expected Output:

bash: /root/unknown_script.sh: No such file or directory
255

Explanation: SSH connects, but the remote script is missing or non-executable. SSH returns 255 to indicate remote execution failure.

Example 6 – Script Exiting Manually with 255

#!/bin/bash
echo "Fatal error occurred!"
exit 255

Expected Output:

Fatal error occurred!
255

Explanation: You can explicitly set exit 255 in Bash to mark fatal failure or stop signal in automation pipelines.

4. Common Scenarios Triggering Exit Code 255

Scenario	Example	Description
SSH host unreachable	ssh user@offlinehost	Network or DNS issue
SSH permission denied	ssh root@vps	Authentication failed
Script out-of-range exit	exit 999	Invalid code (above 255)
Remote command not found	ssh root@server 'nonexistent.sh'	Remote file missing
rsync/scp timeout	rsync /home remote:/backup	Connection dropped
Broken cron job	cron: ssh connection refused	Remote call failed silently

---

5. WordPress VPS Use Cases

Use Case	Example	Explanation
Remote backup via rsync fails	rsync /var/www/html root@backup:/wp/	Destination unreachable → 255
SSH automation from script	ssh root@$remote "wp plugin update --all"	Remote not accessible
Deployment via CI/CD	ssh deploy@server	SSH key missing
Cron job pushing updates	ssh -i /root/key [email protected]	Network failure
Remote database sync	`mysqldump ...	ssh remote mysql ...`
Monitoring script aborts	exit 255	Custom fatal exit condition

---

6. Troubleshooting Matrix

Symptom	Possible Cause	Diagnostic Command	Fix
ssh: connect to host ... timed out	Network issue	ping <host>	Check connectivity
Permission denied	Missing SSH key	ssh-copy-id root@host	Add key
Connection refused	SSH daemon off	systemctl status ssh	Start SSH service
Script exit 255	Out-of-range value	grep exit in script	Keep exit codes ≤255
Cron job fails silently	SSH unreachable	Add set -x or log output	Log SSH errors
rsync stops mid-transfer	Network drop	dmesg / ping	Stabilize network or retry

---

7. Best Practices

1. Validate SSH connectivity before automation:

ssh -o BatchMode=yes -o ConnectTimeout=5 root@host "echo connected"

2. Always check exit status after remote commands:

ssh root@server "wp plugin update --all"
if [ $? -eq 255 ]; then
  echo "SSH connection failed!"
fi

3. Avoid invalid exit codes in scripts:

exit 1  # not exit 999

4. Log every remote command:

ssh root@backup "wp cron event run --due-now" || echo "$(date): exit 255" >> /var/log/ssh_error.log

5. Set connection timeouts:

ssh -o ConnectTimeout=10 root@vps

6. Use retry loops for network resilience:

for i in {1..3}; do ssh root@host "echo test" && break || sleep 5; done

---

8. Quick Lab – Simulate Exit Code 255

Step 1: Connect to invalid host

ssh root@notarealhost
echo $?

Expected Output:

ssh: Could not resolve hostname notarealhost: Name or service not known
255

Step 2: Simulate fatal error in script

cat > /root/fatal_exit.sh <<'EOF'
#!/bin/bash
echo "Unrecoverable error occurred!"
exit 255
EOF
bash /root/fatal_exit.sh

Expected Output:

Unrecoverable error occurred!
255

Explanation: The script explicitly signals a fatal condition.

9. Cheat Sheet

Exit Code	Meaning	Description
0	Success	Command executed successfully
1	General error	Non-specific failure
2	Misuse of shell builtins	Syntax or structure issue
126	Cannot execute	Permission or binary issue
127	Command not found	Missing binary or invalid path
130	Terminated by SIGINT	Manual interrupt (Ctrl+C)
137	Killed by SIGKILL	Forceful termination (OOM)
139	Segmentation fault	Memory access violation
143	Terminated by SIGTERM	Graceful shutdown
255	Abnormal termination	Fatal or unreachable error

---

10. Mini-Quiz

1. What does exit code 255 mean in Bash?
2. Why does ssh root@offline-host return 255?
3. What happens when you use exit 999 inside a script?
4. How can you prevent rsync or scp returning 255?
5. Why is 255 used instead of 256 or higher numbers in Bash?

---

Would you like me to continue next with Exit Status Code = 126 + 127 Combination Handling (Scripted Multi-Command Diagnostics) — which explains how Bash scripts handle mixed error codes (e.g., detecting which command failed in pipelines or chained sequences)?