Debian 9 – dist-upgrade aborts with held broken packages

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

dist-upgrade stops on dependency resolution, delaying patch cycles and security updates.

Environment & Reproduction

Typical on hosts with held packages, mixed repos, or aggressive apt pinning.

# Capture baseline
cat /etc/debian_version
apt-mark showhold
apt-cache policy | sed -n 1,80p
apt-get check

Root Cause Analysis

Held packages and incompatible candidate versions prevent apt from finding a consistent upgrade plan.

Quick Triage

List held packages, broken dependencies, and repository priority conflicts.

# Quick triage
apt-mark showhold
apt-get -s dist-upgrade
apt-cache policy 

Step-by-Step Diagnosis

Use resolver simulation output to identify exact package conflicts and pin effects.

# Detailed diagnosis
apt-get -o Debug::pkgProblemResolver=yes -s dist-upgrade 2>&1 | tee /tmp/apt_resolver_154.log
tail -n 120 /tmp/apt_resolver_154.log

Solution – Primary Fix

Clear unnecessary holds, repair package state, then re-run full upgrade.

# Primary fix
sudo apt-mark unhold 
sudo apt-get -f install
sudo apt-get dist-upgrade

Solution – Alternative Approaches

Temporarily disable third-party sources and test resolution against official archives.

# Alternatives
sudo sed -i s/^deb/# deb/ /etc/apt/sources.list.d/*.list
sudo apt-get update
sudo apt-get -s dist-upgrade

Verification & Acceptance Criteria

dist-upgrade simulation and execution complete with no held or broken package errors.

# Verify
apt-mark showhold
apt-get check
apt-get -s dist-upgrade | sed -n 1,50p

Rollback Plan

Restore prior source and pin files if dependency behavior regresses.

# Rollback
sudo cp /etc/apt/sources.list.bak /etc/apt/sources.list 2>/dev/null || true
sudo apt-get update

Prevention & Hardening

Document package hold intent and repository governance before maintenance windows.

# Hardening
apt-mark showhold > /var/tmp/apt-holds.baseline
apt-cache policy > /var/tmp/apt-policy.baseline

Related Errors & Cross-Refs

Related symptoms include unmet dependencies, package kept back, and no installation candidate.

Related tutorial: View the step-by-step tutorial for Debian 9.

View all Debian 9 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Debian apt resolver internals and package pinning guidance.