Debian First Aid Kit
Author Profile: distro-nix Debian Version: Debian 13 (Trixie) Kernel Versions Tested: 6.12.73+deb13-amd64 and 6.16.3+deb13-amd64 (x86_64) Created: 2025-10-27 Last Updated: 2026-05-15 ID: 544201 License: CC BY-SA 4.0
This guide is preserved in its original form. Questions and feedback welcome via the author’s Debian Forums profile.
Abstract
The Debian First Aid Kit is a practical reference for diagnosing and resolving common system problems on Debian GNU/Linux. It covers commonly occuring categories of failure: system freezes and crashes, boot problems, network issues, package management, disk and filesystem errors, performance degradation, service and application failures, permission and access problems, hardware identification and errors, and quick diagnostics. Each section gives the relevant commands so you can understand what they do and why, rather than a bare list to copy and paste blindly. A dedicated section covers MTR (Matt’s Traceroute) in depth, including how to interpret the output; practical troubleshooting, and how to monitor continuously. The guide also includes a set of shell aliases for faster access to common diagnostic tasks. All commands are verified on Debian 13 (Trixie) running kernel 6.12.73+deb13-amd64 and 6.16.3+deb13-amd64. This document is intended for users with basic command-line familiarity who need a reliable, consolidated reference when something goes wrong.
Keywords: Debian, troubleshooting, system administration, MTR, network diagnostics, package management, journalctl, filesystem repair
Tested Commands Disclaimer
All commands in this document have been verified on Debian 13 (Trixie) with the kernel versions listed above. Results may vary on other releases or hardware configurations. Always test in a safe environment before making changes to a production system.
Conventions Used in This Document
Command examples throughout this guide follow standard Unix prompt conventions. A $ prefix indicates a command run as a regular user. Where elevated privileges are required, sudo is shown explicitly and # with a brief helpful explanation unless it is self-explanatory:
$ journalctl -b -1 # regular user $ sudo apt install mtr # requires elevation via sudo
In recovery shell contexts, where you are operating directly as root, the prompt is #. In these cases, Debian recommends:
$ sudo -i
System Freezes & Crashes
Check System Logs
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
$ free -h # memory usage
$ df -h # disk space
$ htop # interactive resource monitor
$ top # alternative resource monitor
$ sudo apt install btop # btop is a more detailed alternative
$ sudo dmesg | grep -i error # check for disk errors
Access Recovery Mode
Reboot and hold Shift to access the GRUB menu (timing depends on your GRUB configuration). Select “Advanced options”, then choose recovery mode. From the recovery menu, select “root” for a root shell.
Common Boot Fixes
$ sudo fsck /dev/sdXN # repair filesystem — identify device with lsblk first
$ sudo grub-install /dev/sdX # reinstall GRUB bootloader
$ sudo update-grub # regenerate GRUB configuration
$ cat /etc/fstab # check fstab for mount errors
The following are permanent errors caused by incomplete or buggy ACPI tables in the BIOS. They are harmless and can be safely ignored if they appear on your system:
[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
$ systemd-analyze blame # boot time by unit
$ systemd-analyze blame # boot time by unit
$ systemctl --failed # units that failed during boot
$ systemctl status <service-name> # e.g. systemctl status NetworkManager.service
Access Recovery Mode
Reboot and hold Shift to access the GRUB menu (timing depends on your GRUB configuration). Select “Advanced options”, then choose recovery mode. From the recovery menu, select “root” for a root shell.
Common Boot Fixes
$ sudo fsck /dev/sdXN # repair filesystem — identify device with lsblk first
$ sudo grub-install /dev/sdX # reinstall GRUB bootloader
$ sudo update-grub # regenerate GRUB configuration
$ cat /etc/fstab # check fstab for mount errors
Network Issues
Diagnose Network Connection
$ ip addr show # check network interfaces
$ ping -c 4 8.8.8.8 # test IPv4 connectivity
$ ping -c 6 2a00:1450:4007:809::200e # test IPv6 connectivity
$ nslookup google.com # check DNS resolution
$ ip route show # view routing table
$ ss -tuln # check active connections
Restart Network Service
$ sudo systemctl restart NetworkManager # for systems using NetworkManager
$ sudo systemctl restart networking # for systems using networking service
$ sudo ip link set eth0 down # bring interface down
$ sudo ip link set eth0 up # bring interface back up
MTR (Matt’s Traceroute)
MTR combines the functionality of ping and traceroute into a single real-time network diagnostic tool. It continuously monitors the path between your system and a destination, providing detailed statistics about latency and packet loss at each hop. When you need to demonstrate a network problem that is outside your control—to your hosting provider, for example—MTR gives you the evidence you need.
Installation
$ sudo apt install mtr
Basic Usage
$ mtr google.com # interactive mode
$ mtr --report google.com # report mode (10 cycles then exit)
$ mtr --report-cycles 50 google.com # specify number of cycles
$ mtr --tcp google.com # use TCP instead of ICMP
$ mtr --udp google.com # use UDP
$ mtr --no-dns google.com # skip DNS resolution (faster)
$ mtr --show-ips google.com # show both hostnames and IPs
Understanding MTR Output
Sample Output
HOST: hostname Loss% Snt Last Avg Best Wrst StDev 1.|-- 192.168.1.1 0.0% 10 1.2 1.5 1.0 2.3 0.4 2.|-- 10.0.0.1 0.0% 10 8.5 9.2 7.8 12.1 1.3 3.|-- isp-gateway.net 0.0% 10 15.3 16.1 14.2 19.8 1.8 4.|-- ??? 100.0% 10 0.0 0.0 0.0 0.0 0.0 5.|-- google.com 0.0% 10 25.4 26.8 24.1 32.5 2.4
Column Meanings
HOST — Hostname or IP address of each hop in the route.
Loss% — Percentage of packets lost at this hop.
Snt — Number of packets sent to this hop.
Last — Latency of the most recent packet, in milliseconds.
Avg — Average latency across all packets sent, in milliseconds.
Best — Lowest latency recorded, in milliseconds.
Wrst — Highest latency recorded, in milliseconds.
StDev — Standard deviation of latency measurements—lower values indicate a more stable connection.
Interpreting Results
A healthy network shows 0% loss on all hops, stable latency with low StDev values, a gradual latency increase as hop count increases, and consistent response times.
Problem Indicators
1. High Packet Loss at a Specific Hop
5.|-- problem-router.net 25.0% 10 45.3 48.2 42.1 65.8 8.4
If loss continues to the destination, there is a real problem at that router. If loss appears only at that hop but not beyond, the router is likely rate-limiting ICMP responses—a false positive, not a real problem. The rule of thumb: if packet loss appears at hop N but hops N+1, N+2, and beyond show 0% loss, it’s almost certainly ICMP rate limiting.
2. High Latency at a Specific Hop
3.|-- slow-link.net 0.0% 10 150.3 155.2 148.1 165.8 5.4
This indicates a network bottleneck, a congested link, geographical distance (intercontinental hops), or slow routing equipment.
3. No Response (???)
4.|-- ??? 100.0% 10 0.0 0.0 0.0 0.0 0.0
The router at this hop is configured not to respond to ICMP or traceroute packets, or a firewall is blocking diagnostic packets. This is not necessarily a problem if later hops respond normally.
4. High Jitter (StDev)
6.|-- unstable.net 0.0% 10 35.3 52.8 28.1 95.2 24.7
A high StDev (24.7ms in this example) indicates inconsistent latency caused by network congestion or instability. This is particularly noticeable in real-time applications such as VoIP, gaming, and video calls.
5. Sudden Latency Spike
1.|-- 192.168.1.1 0.0% 10 1.2 1.5 1.0 2.3 0.4 2.|-- 10.0.0.1 0.0% 10 8.5 9.2 7.8 12.1 1.3 3.|-- problematic-hop.net 0.0% 10 180.5 185.2 178.1 195.8 6.4 4.|-- next-hop.net 0.0% 10 182.3 187.8 180.5 198.2 6.8
Hop 3 introduces approximately 170ms of additional latency (jumping from 9ms to 180ms). Everything from hop 3 onward carries that penalty.
Advanced Usage
Report Mode with Different Output Formats
$ mtr --report --csv google.com > network-report.csv # CSV for logging $ mtr --report --json google.com # JSON for parsing $ mtr --report --xml google.com # XML format $ mtr --report-wide google.com # wide report, no abbreviations
Protocol Selection
$ mtr google.com # ICMP (default) $ mtr --udp google.com # UDP $ sudo mtr --tcp --port 443 google.com # specific TCP port $ sudo mtr --tcp --port 22 remote-server.com # generally the default port
Timing and Duration
$ mtr --interval 0.5 google.com # interval between pings (default 1s) $ mtr --report-cycles 100 google.com # extended test, 100 cycles $ mtr google.com # continuous monitoring (Ctrl+C to stop) $ mtr --report-cycles 10 google.com # quick 10-cycle report
Advanced Options
$ mtr --aslookup google.com # show Autonomous System (AS) numbers $ mtr --max-ttl 20 google.com # set maximum number of hops $ mtr --psize 1000 google.com # set packet size $ mtr --show-ips google.com # show both IP and hostname $ mtr --address 192.168.1.100 google.com # specify source address $ mtr -4 google.com # IPv4 only $ mtr -6 google.com # IPv6 only
Interactive Mode Commands
When running MTR in interactive mode (mtr hostname), the following keys are available:
h — Display help.
d — Toggle display mode, cycling through different views.
n — Toggle between hostnames and IP addresses.
r — Reset all statistics.
p — Pause/unpause the display.
q — Quit MTR.
u — Switch between ICMP, UDP, and TCP modes.
y — Switch between IPv4 and IPv6.
o — Toggle field display options.
j — Toggle latency display.
Practical Troubleshooting Scenarios
Scenario 1: Diagnosing a Slow Website
$ mtr --report-cycles 100 --no-dns example.com
Look for high average latency at specific hops, packet loss at the destination, and high StDev values indicating jitter.
Scenario 2: Testing if a Firewall Blocks SSH
$ sudo mtr --tcp --port 22 --report-cycles 50 remote-server.com
If the last hop shows 100% loss but earlier hops are fine, port 22 may be filtered. Run a standard ICMP test for comparison.
Scenario 3: ISP Performance Issues
$ mtr --report-cycles 100 8.8.8.8 $ mtr --report-cycles 100 1.1.1.1
If issues appear in the first three or four hops, the problem is likely within your ISP’s network. If issues appear later, the problem lies beyond your ISP.
Scenario 4: VPN Troubleshooting
$ mtr --report-cycles 50 --no-dns google.com > before-vpn.txt # before VPN $ mtr --report-cycles 50 --no-dns google.com > after-vpn.txt # after VPN $ diff before-vpn.txt after-vpn.txt # compare the two
Scenario 5: Gaming/Streaming Performance
$ mtr --report-cycles 200 game-server.com
For real-time applications, look for low average latency (under 50ms for gaming), low StDev (under 5ms preferred), and zero packet loss.
Scenario 6: Intermittent Connectivity
$ mtr --report-cycles 500 --interval 1 target.com > long-test.txt # long-running test $ mtr target.com # real-time monitoring
Continuous Monitoring
Log Network Performance Over Time
while true; do
timestamp=$(date +%Y%m%d-%H%M%S)
mtr --report --report-cycles 50 google.com > "mtr-$timestamp.txt"
sleep 3600
done
Monitor Multiple Destinations
#!/bin/bash echo "=== MTR Report $(date) ===" > daily-network-report.txt echo "" >> daily-network-report.txt echo "Google DNS:" >> daily-network-report.txt mtr --report --report-cycles 50 --no-dns 8.8.8.8 >> daily-network-report.txt echo "" >> daily-network-report.txt echo "Cloudflare DNS:" >> daily-network-report.txt mtr --report --report-cycles 50 --no-dns 1.1.1.1 >> daily-network-report.txt echo "" >> daily-network-report.txt echo "Your Server:" >> daily-network-report.txt mtr --report --report-cycles 50 your-server.com >> daily-network-report.txt
Useful Aliases for .bashrc
Quick network path analysis alias mtrreport='mtr --report --report-cycles 50 --no-dns' Monitor connection to Google DNS alias netcheck='mtr --report-cycles 20 8.8.8.8' Extended network test alias mtrlong='mtr --report-cycles 100' TCP port 443 test (HTTPS) alias mtrhttps='sudo mtr --tcp --port 443 --report-cycles 30' Quick comparison of major DNS providers alias dnstest='echo "Google:" && mtr --report-cycles 20 8.8.8.8 && echo -e "\nCloudflare:" && mtr --report-cycles 20 1.1.1.1'
After adding to ~/.bashrc, reload with:
$ source ~/.bashrc
Useful Tip for Aliases
Rather than adding aliases directly to ~/.bashrc, it's cleaner to keep them in a dedicated file: ~/.bashrc_aliases and source that file from ~/.bashrc. This keeps your shell configuration tidy and makes it easy to share or back up just your aliases without touching the rest of your environment.
Troubleshooting Tips
Permission issues with TCP mode:
$ sudo mtr --tcp --port 443 example.com # Use sudo for TCP on privileged ports $ sudo setcap cap_net_raw+ep /usr/bin/mtr-packet # Or set capabilities (one-time setup)
False positives: Packet loss at an intermediate hop but not at the destination is almost always ICMP rate limiting at that router, not a real problem. Example:
3.|-- router.isp.net 20.0% 50 15.3 16.1 14.2 19.8 1.8 4.|-- next-hop.net 0.0% 50 18.5 19.2 17.8 22.1 1.3 5.|-- destination.com 0.0% 50 25.4 26.8 24.1 32.5 2.4
Hop 3 shows 20% loss, but hops 4 and 5 show 0%. Traffic is flowing normally.
DNS resolution delays: If MTR is slow to start, skip DNS resolution with mtr --no-dns target.com and resolve addresses afterward with host 203.0.113.1 if needed.
Comparing results:
$ mtr --report --report-cycles 50 example.com > test1.txt $ sleep 60 $ mtr --report --report-cycles 50 example.com > test2.txt $ diff test1.txt test2.txt
When to Use MTR vs Other Tools
MTR — Best for continuous monitoring, identifying problem hops, and gathering detailed statistics. Requires installation via apt.
ping — Best for a quick connectivity test or simple latency check. Only tests the endpoint, not the path.
traceroute — Best for one-time path discovery. Provides no continuous monitoring.
ss / netstat — Best for checking local connection status. Doesn’t test remote paths.
Best Practices
Run at least 50–100 cycles for accurate statistics. Use --no-dns for faster results and to avoid DNS resolution issues during testing. Test at different times of day, since network conditions vary. If one protocol shows issues, compare ICMP, UDP, and TCP modes. Save reports with timestamps for trend analysis. Use 8.8.8.8 or 1.1.1.1 as known-good hosts to verify your local network first. Let MTR run for at least 30–60 seconds before drawing conclusions.
Reading Between the Lines
Good network health:
HOST: hostname Loss% Snt Last Avg Best Wrst StDev 1.|-- 192.168.1.1 0.0% 50 1.1 1.2 0.9 2.1 0.2 2.|-- 10.0.0.1 0.0% 50 8.2 8.5 7.5 10.2 0.5 3.|-- isp-gateway.net 0.0% 50 15.1 15.5 14.0 18.3 0.8 4.|-- google.com 0.0% 50 24.8 25.2 23.5 28.1 1.1
No packet loss, consistent latency, low jitter throughout.
Problematic network:
HOST: hostname Loss% Snt Last Avg Best Wrst StDev 1.|-- 192.168.1.1 0.0% 50 1.2 1.5 1.0 2.3 0.3 2.|-- 10.0.0.1 5.0% 50 45.3 52.8 8.1 245.2 45.7 3.|-- ??? 100.0% 50 0.0 0.0 0.0 0.0 0.0 4.|-- destination.com 15.0% 50 95.4 125.8 48.2 385.5 78.2
Packet loss at hop 2 and the destination, high jitter, and a very high worst-case latency all point to a genuine problem at or near hop 2.
Summary
MTR is your friend when it comes to diagnostics. Use --report-cycles 50 or higher for reliable data. Watch for packet loss at the destination—intermediate losses may be false positives. High StDev indicates an unstable connection. High average latency points to slow links. Use --no-dns for faster results. Compare ICMP, UDP, and TCP modes if issues appear. Test at different times of day for a complete picture.
Package Management Issues
Fix Broken Packages
$ sudo apt update # update package lists $ sudo apt --fix-broken install # fix broken dependencies $ sudo dpkg --configure -a # reconfigure packages (no output = nothing to do) $ sudo apt clean # clean package cache $ sudo apt autoclean $ sudo apt autoremove # remove unused packages
Handle Held or Locked Packages
$ sudo lsof /var/lib/dpkg/lock-frontend # find process holding the lock $ sudo rm /var/lib/dpkg/lock-frontend # remove lock (only if no package manager is running) $ sudo rm /var/lib/apt/lists/lock $ sudo dpkg --configure -a # reconfigure dpkg
Disk & Filesystem Issues
Check Disk Health
$ df -h # disk space $ df -i # inode usage $ sudo apt install sysstat # sysstat includes iostat, mpstat, sar, pidstat, cifsiostat $ iostat -x 1 # disk I/O statistics $ iostat -xm 2 # stats in MB instead of KB $ iostat -x sda 1 # monitor a specific device $ sudo dmesg | grep -i "error\|fail" # check for disk errors $ sudo apt install smartmontools $ sudo smartctl -a /dev/sdX # SMART disk health - lsblk to determine the target device
Repair Filesystem
$ sudo umount /dev/sdXN # unmount the partition first $ sudo fsck /dev/sdXN # run filesystem check $ sudo e2fsck -f /dev/sdXN # for ext4 specifically $ sudo apt --fix-broken install # Fix broken dependencies $ sudo dpkg --configure -a # Reconfigure packages
# No output means there is nothing to reconfigure # 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 holding the lock sudo lsof /var/lib/dpkg/lock-frontend # Remove the lock (use with caution—only if no package manager is running) 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 is part of the sysstat package, which also includes: # mpstat (CPU statistics), sar (system activity reporter), # pidstat (process statistics), and cifsiostat (CIFS statistics) sudo apt install sysstat iostat -x 1 # Show stats in MB instead of KB iostat -xm 2 # Monitor a specific device iostat -x sda 1 # Check for disk errors in dmesg sudo dmesg | grep -i "error\|fail" # SMART disk health (requires smartmontools) sudo apt install smartmontools 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 sorted by memory use ps aux --sort=-%mem | head -20
System Temperature Monitoring
# Install lm-sensors if not already present sudo apt install lm-sensors sudo sensors-detect # View temperatures sensors # Real-time temperature monitoring watch -n 2 sensors
See section 12 for a shell alias that makes temperature monitoring more convenient.
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 available application logs ls /var/log/ # Follow syslog for application errors in real-time sudo tail -f /var/log/syslog
Permission & Access Issues
Fix Common Permission Problems
# Check file ownership ls -l /path/to/file # Change ownership (user:group) sudo chown user:group /path/to/file # Change permissions sudo chmod 644 /path/to/file # Recursively fix permissions on a directory 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 (install if needed: sudo apt install lshw) sudo lshw -short # 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 # Press 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 # Full system summary (install if needed: sudo apt install inxi) sudo inxi -Fxz
Emergency Toolkit
# Create a consolidated 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'"
# 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'
# 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 netstatus='ip addr show && echo -e "\n=== Routes ===" && ip route show'
After adding these, reload your shell configuration:
source ~/.bashrc
Tips for Effective Troubleshooting
Check logs first. journalctl and dmesg are your best starting point for almost any problem.
Change one thing at a time. It’s tempting to make several changes at once, but doing so makes it impossible to know what actually fixed—or broke—the problem.
Document your changes. Keep notes on what you’ve tried and what the results were. You’ll thank yourself later.
Use exact error messages. Copy error messages verbatim and search for them alongside “Debian” and the version number—for example, “Debian 13” or “Debian 13.1” for point releases.
Check what changed recently. Did you install something, update packages, or change the kernel before the problem appeared? Start there.
Back up before making major changes. This goes without saying, but it’s easy to skip when you’re in a hurry.
Use verbose mode. Adding -v or -vv flags to commands often reveals what would otherwise be silent failures.
Use the community. The Debian forums, Reddit, Stack Exchange, and the Debian mailing lists are all active and well-indexed. Someone has usually seen your problem before.
This work was contributed by distro-nix to the Debian User Forums on 2025-10-27.