Linux Troubleshooting: A Practical First-Response Guide

Systems break. The difference between a sysadmin who fixes things quickly and one who spirals for hours is usually method, not knowledge. This guide gives you a repeatable first-response process: where to look, what to capture, how to isolate the cause, and how to get useful help when you're stuck.

Step 1: Read the Error Message Fully

This sounds obvious, but most people skim the first line and start Googling before they finish reading. Error messages are dense on purpose. The actionable detail is often in the middle or at the end.

When a command fails, read the full output. Look for:

• The specific error code or string — Permission denied, No such file or directory, Connection refused, Exit code 1
• The file or path named — which config file, socket, or binary triggered the failure
• The service or process involved — especially in multi-component stacks

Copy the exact error text before doing anything else. Paraphrasing it later will cost you search accuracy.

Step 2: Check the Journal

On any systemd-based distro, journalctl is your first stop for deeper context. It captures kernel messages, service output, and application stderr in one place.

Most recent boot, high-priority messages first

journalctl -p err -b

The -p err flag filters to error-level and above. -b means this boot only. This cuts noise dramatically on a busy system.

Follow a specific service live

journalctl -u nginx.service -f

Replace nginx with whatever unit is misbehaving. The -f flag tails output in real time — useful when you're restarting a service to watch what happens.

Check a service's status and recent log tail together

systemctl status sshd.service

This gives the active/failed state, the last few log lines, the PID, and the memory footprint in one compact view. Always run this before diving into the full journal.

Jump to just before a crash

journalctl -b -1 -p err

-b -1 looks at the previous boot — valuable when the system crashed and rebooted before you could check.

Step 3: Isolate the Change

Almost every breakage has a trigger. Something changed: a package updated, a config was edited, a cron job ran, a disk filled up, a user was added. Identifying that change is faster than debugging blindly.

What changed recently on the filesystem?

find /etc -newer /etc/hostname -type f 2>/dev/null

This lists files in /etc modified more recently than /etc/hostname (a file that changes rarely). Adjust the reference file to a known-stable timestamp anchor.

Check recent package activity

On Debian/Ubuntu:

grep " install \| upgrade \| remove " /var/log/dpkg.log | tail -30

On Fedora/RHEL/Rocky:

dnf history list | head -20

On Arch:

grep -E 'installed|upgraded|removed' /var/log/pacman.log | tail -30

Check disk and inode usage

A full disk causes strange, misleading failures. Check it early.

df -h
df -i

df -h shows disk space; df -i shows inode usage. A filesystem can be 0% full by space but 100% full by inodes, which breaks file creation just as hard.

Check for OOM kills

journalctl -k -b | grep -i 'oom\|killed process'

The kernel OOM killer terminates processes without much warning. If a service vanished without a clean exit, this is often why.

Step 4: Reproduce and Narrow Down

Once you have a hypothesis, test it deliberately. Run the failing command manually. Restart the failing service and watch the journal simultaneously in a second terminal. Strip the problem to its smallest reproducible form.

A few practical patterns:

• Run a service in the foreground or in debug mode if it supports it (e.g., nginx -t to test config, sshd -d for debug output)
• Use strace on short-lived processes to see every syscall: strace -e trace=file mycommand reveals missing files and permission errors at the kernel level
• Use lsof -p <PID> to see what files and sockets a running process has open
• Check /tmp and /var/tmp permissions if setuid or sticky-bit behavior is involved

Step 5: Search Effectively

When you need to search for an error, quality of input determines quality of results.

What to include in a search:

• The exact error string in quotes: "failed to connect to bus: no such file or directory"
• The distro and version if the error is likely distro-specific
• The specific service or package name

What to remove from the search:

• Paths or usernames unique to your system (they won't match others' reports)
• Timestamps and PIDs
• Anything that looks like a session or transaction ID

Check the project's issue tracker directly (GitHub, GitLab, Bugzilla) for errors from actively developed software — forum posts go stale, but issues track resolutions. For package-specific bugs on Debian/Ubuntu, bugs.debian.org and Launchpad are authoritative.

Step 6: Ask for Help Well

When you post a question on a forum, mailing list, or chat, the quality of your report determines the quality of answers. A good report has five things:

1. What you were trying to do — the goal, not just the failing command
2. What you expected to happen
3. What actually happened — the exact error, verbatim, as text (not a screenshot)
4. What you've already tried — saves everyone from suggesting dead ends
5. Your environment — distro, version, kernel, relevant package versions

Collect your environment details quickly:

uname -r
cat /etc/os-release
systemctl --version

For a specific package version:

Debian/Ubuntu:

dpkg -l packagename

Fedora/RHEL/Rocky:

rpm -q packagename

Arch:

pacman -Q packagename

Verification: Did the Fix Hold?

After applying a fix, verify it properly rather than just checking the immediate outcome.

• Restart the affected service and confirm it stays up: systemctl is-active servicename
• Check the journal for new errors in the minutes after the fix: journalctl -u servicename --since "5 minutes ago"
• If you edited a config file, validate it before restarting when a validator exists (nginx -t, sshd -t, named-checkconf, postfix check)
• Reboot if the fix involved kernel parameters, kernel modules, or system-wide paths — some changes only fully take effect at boot

Troubleshooting Common Dead Ends

"It works as root but not as my user"

This is almost always permissions (file, socket, or capability) or a missing group membership. Check ls -la on the relevant path, and verify group membership with id username. Remember that group changes require a new login session to take effect.

"The service starts then immediately stops"

Run journalctl -u servicename -b --no-pager and look for the exit code. An exit-code=1 usually means a config error or missing dependency. An exit-code=2 or higher often signals a usage error in the unit file's ExecStart line.

"It was working yesterday and nobody changed anything"

Something changed. Check package update logs (above), check cron jobs that run nightly (cat /etc/cron.daily/*), check for certificate expiry (openssl x509 -in cert.pem -noout -dates), and check disk usage. Automatic updates, logrotate, and certificate rotations are frequent silent triggers.