Welcome to the Debian First Aid Kit!
Maybe you’re completely new to the command line. Either way, you’ve probably discovered something: Debian help is everywhere, but it’s scattered across forums, wikis, and threads—finding the right help when something breaks can feel like searching for a needle in a haystack. This guide exists to change all that. I have compiled the essential fixes and diagnostics you actually need, in one place.
“Anyone can cook.” — Chef Gusteau
Well, anyone can use Debian too. You don’t need to be an expert—you just need the right guidance when things go wrong. And as you get more comfortable with the technology, I have included an Advanced Section to help you move to the next level with Debian. Let’s get started…
How to Use This Guide
If you’re new to Debian:
- Start with the section that matches your problem
- Try the first few commands listed
- Skip sections marked “Advanced” until you need them or want to learn more
- Don’t worry if some commands look complicated – just copy and paste them
The sections get progressively more detailed. Start simple, go deeper only if needed.
System Freezes & Crashes
Check System Logs
# View logs from previous boot (after freeze/crash)
journalctl -b -1
# List all available boots
journalctl --list-boots
# Show only kernel messages from previous boot
journalctl -b -1 -k
# Show errors and critical messages only
journalctl -b -1 -p err
# Save logs to file for analysis
journalctl -b -1 > ~/crash-log.txt
Common Freeze Causes to Look For
- Kernel panics: Search for “kernel panic” or “Oops”
- Out of Memory (OOM): Search for “Out of memory” or “oom-killer”
- Hardware errors: Look for “MCE” (Machine Check Exception) or “hardware error”
- Driver issues: Check for module/driver failures
- Overheating: Check system temperatures
Check System Resources
# View memory usage
free -h
# Check disk space
df -h
# Monitor system resources in real-time
htop
# or
top
(I prefer btop for better presentation)
It’s not installed by default, so here are the steps.
sudo apt install btop
# Check for disk errors
sudo dmesg | grep -i error
These are permanent errors due to incomplete/buggy ACPI tables in the BIOS on my own system. I use them to demonstrate the error messages are nothing to worry about. They are just an example of what you may see with the varied hardware:
0.686554] ACPI Error: No handler for Region [ECRM] (00000000201accc4) [EmbeddedControl] (20250404/evregion-131)
0.686577] ACPI Error: Region EmbeddedControl (ID=3) has no handler (20250404/exfldio-261)
0.686594] ACPI Error: Aborting method _SB.GPIO._EVT due to previous error (AE_NOT_EXIST) (20250404/psparse-529)
Boot Problems
Check Boot Process
# View systemd boot analysis
systemd-analyze blame
# See what failed during boot
systemctl --failed
# Check specific service status
systemctl status # e.g. NetworkManager.service
Access Recovery Mode
- Reboot and hold Shift to access GRUB menu (depending on your grub timing settings)
- Select “Advanced options”
- Choose recovery mode
- Select “root” for root shell access
Common Boot Fixes
# Repair filesystem errors
# Once you identify a device with lsblk
sudo fsck /dev/sdXN
# Reinstall GRUB bootloader
sudo grub-install /dev/sdX
sudo update-grub
# Check fstab for mount errors
cat /etc/fstab
Network Issues
Diagnose Network Connection
# Check network interfaces
ip addr show
# Test connectivity
ping -c 4 8.8.8.8
# or
ping -c 6 2a00:1450:4007:809::200e
# Check DNS resolution
nslookup google.com
# View routing table
ip route show
# Check active connections
ss -tuln
Restart Network Service
# For systems with NetworkManager
sudo systemctl restart NetworkManager
# For systems with networking service
sudo systemctl restart networking
# Bring interface down and up
sudo ip link set eth0 down
sudo ip link set eth0 up
Network Issues
Diagnose Network Connection
# Check network interfaces
ip addr show
# Test connectivity
ping -c 4 8.8.8.8
# or
ping -c 6 2a00:1450:4007:809::200e
# Check DNS resolution
nslookup google.com
# View routing table
ip route show
# Check active connections
ss -tuln
Restart Network Service
# For systems with NetworkManager
sudo systemctl restart NetworkManager
# For systems with networking service
sudo systemctl restart networking
# Bring interface down and up
sudo ip link set eth0 down
sudo ip link set eth0 up
For advanced network path analysis and proving issues to your hosting provider, see the MTR (Advanced Network Diagnostics) section.
Package Management Issues
Fix Broken Packages
# Update package lists
sudo apt update
# Fix broken dependencies
sudo apt --fix-broken install
# Reconfigure packages
sudo dpkg --configure -a
(if no output, there is nothing to do)
# Clean package cache
sudo apt clean
sudo apt autoclean
# Remove unused packages
sudo apt autoremove
Handle Held or Locked Packages
# If apt is locked, find the process
sudo lsof /var/lib/dpkg/lock-frontend
# Force remove lock (use carefully)
sudo rm /var/lib/dpkg/lock-frontend
sudo rm /var/lib/apt/lists/lock
# Reconfigure dpkg
sudo dpkg --configure -a
Disk & Filesystem Issues
Check Disk Health
# Check disk space
df -h
# Check inode usage
df -i
# View disk I/O statistics
iostat -x 1
(Make sure you have sysstat which includes useful performance monitoring tools other than iostat – disk I/O statistics)
- mpstat – CPU statistics
- sar – system activity reporter
- pidstat – process statistics
- cifsiostat – CIFS statistics
# Show stats in MB instead of KB
iostat -xm 2
# Monitor specific device
iostat -x sda 1
# Check for disk errors in dmesg
sudo dmesg | grep -i "error|fail"
# SMART disk health (if smartmontools installed)
sudo smartctl -a /dev/sda
Repair Filesystem
# Unmount the partition first
sudo umount /dev/sdXN
# Run filesystem check
sudo fsck /dev/sdXN
# For ext4 specifically
sudo e2fsck -f /dev/sdXN
Performance Issues
Identify Resource Hogs
# CPU usage by process
top -o %CPU
# Memory usage by process
top -o %MEM
# Disk usage by directory
du -sh /* | sort -h
# Find large files
find / -type f -size +100M 2>/dev/null
# Check running processes
ps aux --sort=-%mem | head -20
System Temperature Monitoring
# Install sensors (if not installed)
sudo apt install lm-sensors
sudo sensors-detect
# View temperatures
sensors
# Real-time temperature monitoring
watch -n 2 sensors
I have it as an alias in ~/.bashrc
Go to 11. Useful Aliases & Shortcuts
Service & Application Errors
Debug Service Problems
# Check service status
sudo systemctl status service-name
# View service logs
sudo journalctl -u service-name
# Restart a service
sudo systemctl restart service-name
# Enable service at boot
sudo systemctl enable service-name
# View recent service failures
journalctl -p err -b
Application Crash Investigation
# Check for core dumps
ls -lh /var/crash/
# View application-specific logs
ls /var/log/
# Check syslog for application errors
sudo tail -f /var/log/syslog
Permission & Access Issues
Fix Common Permission Problems
# Check file ownership
ls -l /path/to/file
# Change ownership
sudo chown michael:michael /path/to/file
# user:group
# Change permissions
sudo chmod 644 /path/to/file
# Recursively fix permissions
sudo chown -R user:group /path/to/directory
User & Authentication Issues
# Check user information
id username
# View user login history
last -a
# Check failed login attempts
sudo journalctl | grep "authentication failure"
# Reset user password
sudo passwd username
Hardware Issues
Identify Hardware
# List all hardware
sudo lshw -short
(May not be installed by default)
sudo apt install lshw
# PCI devices
lspci -v
# USB devices
lsusb -v
# CPU information
lscpu
# Memory information
sudo dmidecode --type memory
Check Hardware Errors
# Kernel ring buffer (hardware messages)
dmesg | less
(If no output, good, no errors)
q to quit
# Search for specific hardware issues
dmesg | grep -i "error|fail|warn"
# Check for USB issues
dmesg | grep -i usb
Quick Diagnostic Commands
System Information at a Glance
# Uptime and load average
uptime
# Kernel version
uname -r
# Debian version
cat /etc/debian_version
# System summary
sudo inxi -Fxz
Emergency Toolkit
# Create a diagnostic report
sudo journalctl -b > ~/system-report.txt
dmesg >> ~/system-report.txt
systemctl --failed >> ~/system-report.txt
df -h >> ~/system-report.txt
free -h >> ~/system-report.txt
# Watch logs in real-time
sudo journalctl -f
# Monitor system resources continuously
watch -n 1 'free -h && df -h'
Useful Aliases & Shortcuts
Add these to your ~/.bashrc for quick access to common troubleshooting commands:
# Monitor system temperatures in real-time
alias temps="watch -n 2 'for i in /sys/class/hwmon/hwmon*/; do echo -n "$(cat ${i}name): "; cat ${i}temp*_input 2>/dev/null | while read temp; do echo "scale=1; $temp/1000" | bc; done | tr "n" " "; echo "°C"; done'"
or run the watch command in the shell without the opening and closing double quotes.
# Quick system status
alias sysstat='echo "=== CPU ===" && uptime && echo -e "n=== Memory ===" && free -h && echo -e "n=== Disk ===" && df -h && echo -e "n=== Top Processes ===" && ps aux --sort=-%mem | head -10'
(It’s a messy layout, but I’m terrible with awk. Feel free to improve the layout for me)
# View last boot logs
alias lastboot='journalctl -b -1'
# Check failed services
alias failedservices='systemctl --failed'
# Monitor logs in real-time
alias watchlog='sudo journalctl -f'
# Quick network status
alias netstat='ip addr show && echo -e "n=== Routes ===" && ip route show'
After adding these, run:
source ~/.bashrc
Tips for Your Troubleshooting
- First check logs: journalctl and dmesg are your best friends
- Work through the sections: Change one thing at a time
- Document changes: Keep notes on what you’ve tried
- Search for error messages: Copy exact error messages into search engines or AI
- Check recent changes: What you did before it happened? Install something, update packages, kernel?
- Make backups: Before major changes, backup important data
- Use verbose mode: Add -v or -vv flags to commands for more detail
- Check forums: Debian forum, Reddit, Stack Exchange, and mailing lists
Remember: If in doubt, search for the specific error message along with “Debian” and the version number. e.g. Debian 13 or point release if needed, Debian 13.1
As usual I welcome any comments, suggestions or resources:
dev@divsmart.com or distro-nix on Debian Forum.
