Debian 12 – 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

Upgrade workflows stop with unresolved dependency sets and security patching delays.

Environment & Reproduction

Seen with package holds, mixed repos, or conflicting apt pin priorities.

Root Cause Analysis

Resolver cannot find a consistent install set due to held or incompatible package candidates.

Quick Triage

List holds, verify enabled repositories, and run resolver simulation.

Step-by-Step Diagnosis

Pinpoint exact dependency conflicts before changing package state.
– shell: `sudo apt-mark showhold && sudo apt -o Debug::pkgProblemResolver=yes dist-upgrade -s`
– python: `python3 -c “import subprocess; print(subprocess.getoutput(‘apt policy | head -n 120’))”`
– perl: `perl -e ‘print q{Capture resolver output for change records}’`

Solution – Primary Fix

Clear unnecessary holds, align repositories, then re-run upgrade.
– shell: `sudo apt-mark unhold && sudo apt update && sudo apt dist-upgrade`
– python: `python3 -c “import subprocess; print(subprocess.getoutput(‘sudo apt -f install’))”`
– perl: `perl -e ‘print q{Validate no kept-back critical packages remain}’`

Solution – Alternative Approaches

Temporarily disable third-party sources and retry with only official Debian archives.

Verification & Acceptance Criteria

dist-upgrade simulation and execution complete with zero broken package messages.

Rollback Plan

Restore prior apt source and pin files if dependency behavior worsens.

Prevention & Hardening

Apply repository governance and hold lifecycle reviews before maintenance windows.

Related Errors & Cross-Refs

Related to unmet dependencies, kept back packages, and no installation candidate.

Related tutorial: View the step-by-step tutorial for debian-12.

View all debian-12 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Debian apt resolver debugging and apt pinning documentation.