Common Debian System Errors and How to Fix Them

Here are the most frequently encountered real-world errors on Debian systems (especially Debian 12 Bookworm → Debian 13 Trixie transition period, 2025–2026), ordered roughly by how often administrators see them.

For each error I include:

• typical full message or symptom
• most common root causes in production
• the fastest & safest way to diagnose
• the usual fix (with reasoning)

1. “E: Unable to locate package …”

Symptom E: Unable to locate package nginx / E: Package ‘docker-ce’ has no installation candidate

Most common causes (2026)

1. Forgot to run apt update after adding a new repository
2. Typo in package name
3. Trying to install a package from a different suite (testing/sid) without proper pinning
4. Third-party repo added but architecture or release codename mismatch (e.g. bookworm vs trixie)

Quick diagnosis

apt update
apt search ^package-name
apt policy package-name
lsb_release -sc   # check codename

Fixes (in order of preference)

• sudo apt update && sudo apt install <correct-package-name>
• For Docker / NVIDIA / VirtualBox / etc. → follow official instructions exactly (they usually provide ready-to-paste sources.list.d file)
• If you added a PPA-style repo → verify /etc/apt/sources.list.d/*.list contains correct codename (trixie, not bookworm)

2. “The following packages have unmet dependencies”

Symptom The following packages have unmet dependencies: … E: Unable to correct problems, you have held broken packages.

Most common causes

1. Mixed suites without proper pinning (stable + testing + backports)
2. Held packages (apt-mark hold)
3. Third-party repo with newer version conflicting with Debian dependencies
4. Interrupted apt run → inconsistent state

Quick diagnosis

apt update
apt list --upgradable
apt-mark showhold
apt policy <problem-package>

Fixes

• sudo apt update && sudo apt install -f (most common quick fix)
• sudo apt full-upgrade (allows removals)
• sudo apt-mark unhold <package> if you see held packages
• Remove or comment out problematic third-party repos temporarily
• Use aptitude interactive resolver when desperate (it suggests more solutions)

3. “dpkg was interrupted, you must manually run ‘dpkg –configure -a’”

Symptom Package manager stuck after power loss / Ctrl+C / crash

Fix

sudo dpkg --configure -a
sudo apt install -f

Why it happens dpkg uses lock files and state tracking — interruption leaves packages in half-configured state.

Prevention tip Use tmux or screen when doing long upgrades over SSH.

4. “Failed to start … Unit … has begun starting up again (restart limit reached).”

Symptom journalctl -u nginx or systemctl status mariadb shows restart loop

Most common causes

1. Configuration syntax error
2. Missing directory / permission denied
3. Port already in use
4. Out of memory / too many open files

Quick diagnosis

sudo journalctl -u servicename -xe      # last errors
sudo systemctl status servicename --no-pager -l
sudo ss -tulnp | grep :80               # port conflict example

Fix pattern

• Fix obvious config error → systemctl restart servicename
• Check permissions: ls -ld /var/lib/mysql / /var/log/nginx
• Increase limits if OOM-related: /etc/systemd/system/<service>.d/override.conf

5. “ssh_exchange_identification: read: Connection reset by peer”

Symptom Cannot SSH after hardening or reboot

Most common causes (after hardening guide)

1. PermitRootLogin no + trying to login directly as root
2. PasswordAuthentication no + no key copied
3. AllowUsers / AllowGroups doesn’t include your user
4. fail2ban banned your IP
5. nftables / ufw blocking new port

Quick diagnosis & fix

• Check from console (VPS panel / rescue mode)
• journalctl -u ssh or tail -n 50 /var/log/auth.log
• fail2ban-client status sshd → fail2ban-client set sshd unbanip YOUR.IP
• Verify /etc/ssh/sshd_config syntax: sshd -t

6. “Temporary failure in name resolution”

Symptom ping google.com fails, but ping 8.8.8.8 works

Most common causes

1. /etc/resolv.conf overwritten or empty
2. systemd-resolved not running
3. NetworkManager / systemd-networkd misconfigured DNS
4. Container/VM with broken network namespace

Fixes

• systemctl status systemd-resolved → restart if dead
• sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
• Check /etc/systemd/resolved.conf → DNS=8.8.8.8 1.1.1.1

7. “read-only file system” or mount errors on boot

Symptom Boot stuck or root filesystem mounted read-only

Most common causes

1. Filesystem errors (power loss, bad sectors)
2. fstab typo (wrong UUID, wrong mount point)
3. LVM / mdadm / encryption initramfs problem
4. Disk full → journald / systemd cannot write

Quick diagnosis (from recovery mode / live USB)

fsck -f /dev/mapper/debian--vg-root
journalctl -b -1   # previous boot
blkid              # verify UUIDs in /etc/fstab

Fix pattern

• Run fsck on unmounted filesystem
• Comment out bad line in /etc/fstab
• Regenerate initramfs: update-initramfs -u -k all

8. “No space left on device” (but df shows free space)

Symptom apt, journalctl, logs, services fail — but df -h looks okay

Most common causes

1. Inode exhaustion (millions of small files)
2. /var/log/journal huge
3. Reserved blocks on ext4 (5% default)

Diagnosis

df -i              # inode usage
du -shx /var/log/* # log hogs
tune2fs -l /dev/sdX | grep "Reserved block"

Fixes

• journalctl –vacuum-time=2weeks
• apt autoclean && apt autoremove
• Delete old kernels: apt autoremove –purge
• tune2fs -m 1 /dev/sdX (reduce reserved to 1%)

Quick General Recovery Cheat Sheet

Most Debian problems are state inconsistencies (package db, systemd units, mounts) rather than deep corruption — which is why the system is usually recoverable with 3–5 commands if you keep calm and read the error messages carefully.

Save this mental checklist — it covers ~85–90% of real incidents you’ll see in production or homelab Debian systems.