funwithlinux guide

Troubleshooting Common Linux Issues: A Practical Guide

Linux, celebrated for its stability, security, and flexibility, is not immune to issues. Whether you’re a seasoned sysadmin, a developer, or a new user, encountering problems like boot failures, network glitches, or permission errors is inevitable. The key to resolving these issues lies in **systematic troubleshooting**—understanding the root cause, using the right tools, and applying targeted fixes. This guide demystifies common Linux problems with step-by-step solutions, practical examples, and essential tools. By the end, you’ll be equipped to diagnose and resolve issues efficiently, turning frustration into confidence.

Table of Contents

  1. Boot Issues: When Linux Refuses to Start
  2. Network Problems: No Internet or Slow Connectivity
  3. Package Management Headaches: Broken Dependencies & Failed Updates
  4. Disk Space Woes: Running Out of Storage
  5. Permission Errors: “Permission Denied” Messages
  6. Service Failures: When systemd Services Won’t Start
  7. GUI Troubles: Black Screens, Unresponsive Desktops, & Display Issues
  8. Performance Lags: Slow System, High CPU/RAM Usage
  9. Kernel Issues: Panics, Module Conflicts, & Hardware Incompatibility
  10. General Troubleshooting Methodology: A Systematic Approach
  11. Conclusion
  12. References

1. Boot Issues: When Linux Refuses to Start

Boot problems are among the most critical—if Linux won’t start, you can’t access your system. Common symptoms include GRUB errors, kernel panics, or a frozen boot screen.

Common Causes

  • Corrupted GRUB (Grand Unified Bootloader) configuration.
  • Failed kernel update or incompatible kernel version.
  • Faulty hardware (e.g., failing hard drive, RAM issues).
  • Misconfigured init system (e.g., systemd errors).

Troubleshooting Steps

Scenario 1: GRUB Menu Missing or Errors

If GRUB fails to load (e.g., “error: file not found”), use a Linux live USB to repair it:

  1. Boot from the live USB and open a terminal.
  2. Identify your Linux root partition with lsblk (look for /dev/sdaX or /dev/nvme0n1pX).
  3. Mount the root partition: 
    sudo mount /dev/sdaX /mnt
  4. Chroot into the mounted system: 
    sudo chroot /mnt
  5. Reinstall GRUB (for BIOS systems): 
    grub-install /dev/sda  # Replace /dev/sda with your disk (not partition!)  
update-grub
    For UEFI systems, mount the EFI partition first: 
    sudo mount /dev/sdaY /mnt/boot/efi  # /dev/sdaY is your EFI partition (FAT32)  
grub-install --target=x86_64-efi --bootloader-id=GRUB /dev/sda

Scenario 2: Kernel Panic During Boot

A kernel panic (e.g., “Kernel panic - not syncing: VFS: Unable to mount root fs”) often occurs due to a corrupted kernel. Fix it by:

  1. Reboot and hold Shift (BIOS) or Esc (UEFI) to access the GRUB menu.
  2. Select an older kernel version from the “Advanced options” menu.
  3. Once booted, remove the problematic kernel: 
    sudo apt remove linux-image-<version>-generic  # Debian/Ubuntu  
sudo dnf remove kernel-<version>  # RHEL/Fedora
  4. Update GRUB to reflect changes: sudo update-grub.

Scenario 3: System Hangs at “Loading Initial Ramdisk”

This may indicate a hardware or driver conflict. Check for faulty RAM with memtest86+ (boot from live USB and run the tool). For driver issues, blacklist problematic modules (e.g., faulty GPU drivers) by editing /etc/modprobe.d/blacklist.conf and adding:

blacklist <module-name>

2. Network Problems: No Internet or Slow Connectivity

Network issues range from “no internet” to DNS failures or slow speeds. The goal is to isolate whether the problem is local (your machine), router, or ISP-related.

Common Causes

  • Misconfigured network interfaces (e.g., static IP conflicts).
  • Firewall blocking traffic (e.g., ufw, iptables).
  • DNS server failures or incorrect DNS settings.
  • Faulty network hardware (e.g., Ethernet cable, Wi-Fi adapter).

Troubleshooting Steps

Step 1: Check Interface Status

Use ip addr to verify if your network interface (e.g., eth0, wlan0) has an IP address:

ip addr show eth0  # Replace eth0 with your interface
  • If no IP (e.g., inet 0.0.0.0), your DHCP server isn’t assigning an address. Restart the network service: 
    sudo systemctl restart NetworkManager  # For NetworkManager  
sudo systemctl restart systemd-networkd  # For systemd-networkd

Step 2: Test Connectivity

  • Ping your router (e.g., ping 192.168.1.1). If it fails, check Ethernet/Wi-Fi hardware.
  • Ping a public IP (e.g., ping 8.8.8.8). If this works but ping google.com fails, DNS is broken.

Step 3: Fix DNS Issues

Edit /etc/resolv.conf (temporarily) or set DNS via NetworkManager:

sudo nano /etc/resolv.conf

Add public DNS servers:

nameserver 8.8.8.8  # Google DNS  
nameserver 1.1.1.1  # Cloudflare DNS

For permanent changes, use nmcli (NetworkManager):

nmcli con mod "Wired connection 1" ipv4.dns "8.8.8.8,1.1.1.1"  
nmcli con up "Wired connection 1"

Step 4: Check Firewall Rules

A misconfigured firewall can block traffic. Temporarily disable ufw to test:

sudo ufw disable

If connectivity returns, re-enable and adjust rules:

sudo ufw allow 80/tcp  # Allow HTTP  
sudo ufw allow 443/tcp  # Allow HTTPS  
sudo ufw enable

3. Package Management Headaches: Broken Dependencies & Failed Updates

Package managers like apt (Debian/Ubuntu) or dnf (RHEL/Fedora) simplify software installation, but broken dependencies or corrupted caches can derail updates.

Common Causes

  • Interrupted updates (e.g., power loss during apt upgrade).
  • Third-party repositories conflicting with official ones.
  • Missing dependencies for a package.

Troubleshooting Steps

Scenario 1: “Broken Packages” in apt

Fix with:

sudo apt clean  # Clear cached packages  
sudo apt autoremove  # Remove unused dependencies  
sudo apt --fix-broken install  # Repair broken dependencies

Scenario 2: Stuck on “Waiting for Cache Lock”

This happens when another package manager (e.g., dpkg, synaptic) is running. Kill the process:

sudo lsof /var/lib/dpkg/lock-frontend  
sudo kill -9 <PID>  # Replace <PID> with the process ID  
sudo dpkg --configure -a  # Resume interrupted dpkg operations

Scenario 3: Third-Party Repo Conflicts

If a PPA or third-party repo causes errors, disable it:

sudo add-apt-repository --remove ppa:repo-name/ppa  # Debian/Ubuntu  
sudo rm /etc/yum.repos.d/repo-name.repo  # RHEL/Fedora

4. Disk Space Woes: Running Out of Storage

Running out of disk space can crash services, corrupt files, or prevent updates.

Common Causes

  • Large log files (e.g., /var/log).
  • Unnecessary packages or cached files.
  • Accidental storage of big files (e.g., backups, ISOs).

Troubleshooting Steps

Step 1: Identify Disk Usage

Check overall disk space with df -h (human-readable):

df -h  
Filesystem      Size  Used Avail Use% Mounted on  
/dev/sda2       200G  180G   10G  95% /  # Root partition is 95% full!

Check inode usage (critical for file metadata) with df -i:

df -i  
Filesystem      Inodes  IUsed   IFree IUse% Mounted on  
/dev/sda2      1280000 1280000      0  100% /  # Inodes exhausted!

Step 2: Free Up Space

  • Delete large files: Use du to find files >1GB: 
    sudo du -h / --max-depth=1 | sort -rh | head -10
  • Clean logs: Truncate large log files (e.g., /var/log/syslog): 
    sudo truncate -s 0 /var/log/syslog
  • Clear package caches: 
    sudo apt clean  # Debian/Ubuntu  
sudo dnf clean all  # RHEL/Fedora

Step 3: Resize Partitions (If Using LVM)

If you’re using LVM (Logical Volume Manager), extend the root partition:

  1. Check free space in the volume group: 
    vgs  # Look for "VFree"
  2. Extend the logical volume: 
    sudo lvextend -L +50G /dev/ubuntu-vg/root  # Add 50GB
  3. Resize the filesystem: 
    sudo resize2fs /dev/ubuntu-vg/root  # For ext4  
sudo xfs_growfs /dev/ubuntu-vg/root  # For XFS

5. Permission Errors: “Permission Denied” Messages

“Permission denied” errors occur when your user lacks access to files/directories. Linux uses a robust permission system (user, group, others) to secure data.

Common Causes

  • Incorrect file permissions (e.g., rw------- for a shared file).
  • Wrong owner/group (e.g., a file owned by root but accessed by a regular user).

Troubleshooting Steps

Understand Permissions

Use ls -l to check permissions:

ls -l file.txt  
-rw-r--r-- 1 alice users 1024 Oct 5 12:00 file.txt
  • rw-r--r--: User (alice) can read/write, group (users) can read, others can read.
  • Permissions are numeric: r=4, w=2, x=1. rw-r--r-- = 644.

Fix Permissions

  • Change permissions with chmod: 
    chmod 644 file.txt  # User: rw, Group: r, Others: r  
chmod +x script.sh  # Add execute permission for all
  • Change owner/group with chown: 
    sudo chown alice:users file.txt  # Owner: alice, Group: users

Dangerous Pitfalls

Avoid chmod 777 (full access for everyone)—it’s a security risk! Use the principle of least privilege.

6. Service Failures: When systemd Services Won’t Start

systemd manages most Linux services (e.g., nginx, ssh). If a service fails to start, logs and status checks are your best tools.

Troubleshooting Steps

Step 1: Check Service Status

Use systemctl status to diagnose:

systemctl status nginx  
● nginx.service - A high performance web server  
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)  
   Active: failed (Result: exit-code) since Thu 2023-10-05 14:30:00 UTC; 5s ago  
  Process: 1234 ExecStart=/usr/sbin/nginx -g daemon on; master_process on; (code=exited, status=1/FAILURE)

Step 2: View Service Logs

Use journalctl to trace errors:

sudo journalctl -u nginx -f  # -f = "follow" live logs

Look for clues like “address already in use” (port conflict) or “permission denied” (incorrect config file permissions).

Step 3: Fix the Service

  • Port conflict: Identify the process using the port (e.g., 80): 
    sudo lsof -i :80
    Kill it with sudo kill -9 <PID>, then restart the service.
  • Corrupted config: Validate the service’s config file: 
    nginx -t  # For nginx  
apache2ctl configtest  # For Apache

7. GUI Troubles: Black Screens, Unresponsive Desktops, & Display Issues

Graphical User Interface (GUI) issues can range from minor annoyances (e.g., wrong resolution) to showstoppers (e.g., black screen on login).

Common Causes

  • Outdated or incompatible graphics drivers (e.g., NVIDIA/AMD proprietary drivers).
  • Corrupted Xorg or Wayland configuration.
  • Desktop environment (DE) crashes (e.g., GNOME, KDE).

Troubleshooting Steps

Scenario 1: Black Screen After Login

  1. Switch to a TTY (text terminal) with Ctrl+Alt+F3.
  2. Check Xorg logs for errors: 
    cat /var/log/Xorg.0.log | grep -i error
  3. Reinstall graphics drivers:
    • NVIDIA: sudo apt install nvidia-driver-535
    • AMD: sudo apt install xserver-xorg-video-amdgpu
  4. Restart the display manager: 
    sudo systemctl restart gdm  # For GNOME  
sudo systemctl restart sddm  # For KDE

Scenario 2: Incorrect Display Resolution

  1. List available resolutions with xrandr: 
    xrandr
  2. Set a valid resolution (e.g., 1920x1080): 
    xrandr --output HDMI-1 --mode 1920x1080
  3. Persist the change by adding the command to ~/.xprofile.

8. Performance Lags: Slow System, High CPU/RAM Usage

A slow Linux system is often due to resource bottlenecks (CPU, RAM, disk I/O).

Troubleshooting Steps

Identify Resource Hogs

Use htop (interactive) or top to monitor CPU/RAM usage:

htop

Look for processes with high %CPU or RES (resident memory).

Check for Swap Usage

Excessive swap usage (disk used as RAM) slows the system. Check with free -h:

free -h  
              total        used        free      shared  buff/cache   available  
Mem:           15Gi       12Gi       1.0Gi       500Mi       2.0Gi       2.5Gi  
Swap:          20Gi        18Gi       2.0Gi  # High swap usage!

Fix by closing memory-heavy apps or increasing physical RAM.

Disk I/O Bottlenecks

Use iostat to check disk read/write speeds:

sudo iostat -x 5  # Run every 5 seconds

High %util (e.g., >90%) indicates a slow disk. Upgrade to an SSD or clean up disk usage.

9. Kernel Issues: Panics, Module Conflicts, & Hardware Incompatibility

The Linux kernel is the core of the OS. Issues here can cause system instability.

Troubleshooting Steps

Update the Kernel

New kernels often fix bugs. Update with:

sudo apt upgrade linux-image-generic  # Debian/Ubuntu  
sudo dnf upgrade kernel  # RHEL/Fedora

Blacklist Problematic Modules

If a kernel module (e.g., nouveau for NVIDIA) causes issues, blacklist it:

  1. Create a .conf file in /etc/modprobe.d/: 
    sudo nano /etc/modprobe.d/blacklist-nouveau.conf
  2. Add: 
    blacklist nouveau  
options nouveau modeset=0
  3. Rebuild the initramfs: 
    sudo update-initramfs -u

10. General Troubleshooting Methodology: A Systematic Approach

To resolve issues efficiently, follow this workflow:

  1. Reproduce the Issue: Ensure the problem occurs consistently (e.g., “Does the network fail only on Wi-Fi?”).
  2. Check Logs: Use journalctl (system logs), /var/log/ (application logs), and dmesg (kernel messages).
  3. Isolate Variables: Test one change at a time (e.g., disable a service, update one package).
  4. Use Tools: Leverage diagnostic tools (htop, ip, df) to gather data.
  5. Document Fixes: Note what worked (or didn’t) for future reference.

Conclusion

Troubleshooting Linux issues is a skill that grows with practice. By understanding common problems, using the right tools, and following a systematic approach, you can resolve most issues quickly. Remember: logs are your best friend, and the Linux community (forums, docs, tutorials) is always there to help.

References