Handling System Errors: A Linux Debugging Guide for Developers

Previously in this course, we covered remote file transfers with scp and rsync. While those tools handle data movement, sometimes things go wrong—files don't move, scripts hang, or services fail to start. This lesson adds a layer of diagnostic intelligence to your workflow, moving you from "guessing" why a command failed to systematically identifying the root cause.

The Anatomy of an Exit Code

In Linux, every command you execute communicates its success or failure back to the shell via an exit code (also called a return code). When a command finishes, it returns an integer between 0 and 255.

By convention:

• 0 means "Success."
• 1–255 indicate various types of errors.

You can inspect the exit code of the most recently executed command by checking the special shell variable $?.

Bash
# Try listing a directory that doesn't exist
ls /nonexistent_folder
# Output: ls: cannot access '/nonexistent_folder': No such file or directory

# Now check the exit code
echo $?
# Output: 2

In this case, 2 indicates a misuse of shell built-ins or a "No such file or directory" error. As you continue your career, you will encounter interpreting stack traces in application code, but at the system level, $? is your primary diagnostic tool.

Debugging Permission Denied Errors

"Permission denied" is the most common hurdle for new developers. It usually happens when you try to read, write, or execute a file without the necessary file permissions.

If you encounter this, follow these diagnostic steps:

1. Verify Ownership: Use ls -l to see who owns the file. If you aren't the owner or in the right group, you can't touch it.
2. Check Parent Directories: You need "execute" (x) permissions on every directory in the path to reach a file. If you can't cd into a directory, you can't read files inside it.
3. Use sudo (Carefully): If you are an administrator and legitimately need to access the file, use sudo.

Bash
# Example of a failure
cat /etc/shadow
# Output: cat: /etc/shadow: Permission denied

# Correcting with sudo
sudo cat /etc/shadow

Troubleshooting Missing Dependencies

When a command returns "command not found," it usually means the executable is either not installed or not in your $PATH. We previously explored the PATH variable, but often the issue is simpler: the package is just missing.

If you are working on your web server project and try to run a tool like nginx or curl and it fails, verify if it exists first:

• Which command: Run which <command> to see if the shell can locate it. If it returns nothing, the binary isn't in your path.
• Package manager check: If you know the tool should be there, try searching your package manager (e.g., apt search <package>).

Hands-on Exercise: The Broken Script

Let’s apply this to our ongoing project. Navigate to your project directory and create a file named debug_test.sh:

1. Open a new file: nano debug_test.sh
2. Add this content:

   Bash
   #!/bin/bash
   cat /root/secret.txt
   

3. Save and run it: ./debug_test.sh

Your Challenge:

1. Execute the script and observe the error.
2. Check the exit code using echo $?.
3. Explain why it failed (hint: look at the path and the permissions of /root).
4. Fix the script by pointing it to a file you actually have access to, then verify the exit code is 0.

Common Pitfalls

• Assuming 1 is the only error code: While 1 is a generic "catch-all" error, specific tools have their own codes. Always check the man page of the tool you are using if you see a weird error code.
• Ignoring stderr: Remember that errors are printed to Standard Error (stderr). If you are redirecting output, don't accidentally hide your error messages using >. Use 2> to capture or log errors specifically, as discussed in standard streams and redirection.
• Forgetting sudo: Trying to fix a permission error by changing file permissions (chmod 777) instead of using sudo is a major security risk.

FAQ

Q: Is there a way to see the error code of a command that isn't the last one run? A: No, $? is overwritten immediately after every command. If you need to save an error code, copy it to a variable immediately: command; err=$?; echo $err.

Q: Why does my script exit immediately when one command fails? A: You likely have set -e at the top of your script. This causes the script to exit immediately if any command returns a non-zero status. It's a great practice for preventing cascading failures.

Recap

Debugging is a core engineering skill. By using exit codes ($?), checking permissions, and verifying your environment path, you can resolve 90% of the issues you'll encounter on a Linux server. Always check your exit codes, verify ownership, and ensure your dependencies are in the correct location.

Up next: We will dive into Advanced Process Priority, where we'll learn how to ensure our web server processes get the CPU resources they need when the system is under heavy load.