Linux Troubleshooting — The Complete Guide

Linux Troubleshooting — The Complete Guide#

Most Linux firefighting comes down to the same handful of symptoms: the box is slow, the disk is full, memory is gone, a service won't start, or something is "permission denied." Each has a cause you can pin down in minutes once you know which command to reach for. This guide is the map: for each common problem it says what the symptom actually means, the command that reveals the cause, and where the full fix lives.

Before diagnosing anything specific, four commands give you the lay of the land:

uptime                 # load average over 1, 5, 15 minutes
free -h                # memory and swap, human-readable
df -h                  # disk usage per filesystem
journalctl -p err -b   # errors since the last boot

Those four answer "is it CPU, memory, disk, or a service?" faster than anything else.

"The box is slow"#

• High load average: load counts everything waiting to run, including processes stuck in uninterruptible I/O sleep, so high load is not always CPU. Sorting it out is in diagnosing high load average.
• High CPU: when load really is CPU, the question is which process and whether it's user, system, or iowait time. Tracked down in debugging high CPU on Linux.
• Disk I/O bottleneck: sometimes "slow" is a saturated disk, not CPU. The deeper tuning angle is in Linux performance tuning for containers and Kubernetes nodes.

"It's out of memory"#

• Find what's eating RAM: telling real usage (RSS) from cache and shared memory is where most people misread free. Explained in find what's using your memory.
• The OOM killer fired: a process got killed and you want to know why and how to prevent it. Covered in the Linux OOM killer, with the early-warning signal in memory pressure (PSI) before OOM. The container versions are Docker exit 137 and Kubernetes OOMKilled.

"The disk is full"#

• No space left on device: the classic trap is df showing full while du disagrees, usually a deleted-but-still-open file or exhausted inodes. Both are handled in disk full when df says otherwise.

"It won't open, bind, or start"#

• Too many open files: hitting the file-descriptor limit under load, fixed with the right ulimit and systemd settings. Walked through in fixing too many open files.
• Address already in use: another process holds the port, or a stale socket lingers in TIME_WAIT. Fixed in address already in use.
• Permission denied: ownership, mode bits, ACLs, or SELinux, in that order of likelihood. Diagnosed fast in Linux permission denied, with the fundamentals in Linux file permissions explained.
• A systemd service won't start: the unit fails and you need the real error, not "failed." Read out of the logs in debugging a systemd service that won't start.

"The network is acting up"#

Connectivity, DNS, and socket-level problems get their own deep dive with packet capture in Linux network debugging with tcpdump, ss, and eBPF.

The mental model#

Almost every Linux problem sorts into one of four buckets: CPU/scheduling (load, high CPU), memory (usage, swap, OOM), storage (disk full, inodes, I/O), or a resource limit (file descriptors, ports, permissions). Naming the bucket from uptime, free, and df turns a vague "it's broken" into a short checklist. The tools rarely change from one distro to the next, which is why building these into reflexes pays off for years.

The call we'd make#

Run the four orientation commands before you touch anything, because guessing wastes more time than measuring. Learn to read load versus CPU, RSS versus cache, and df versus du, since those three distinctions explain most false alarms. Each linked guide is the fast path for one specific symptom. Linux is not mysterious once you know where it keeps the evidence: the logs, /proc, and a dozen commands tell you exactly what happened, every time.