Diagnosing apt Held-Back Packages and Dependency Conflicts on Debian Stable

The Symptom: Held-Back Packages and Unmet Dependencies

Enabling stable-backports or adding a third-party repository to Debian stable can turn a routine apt upgrade into a wall of kept-back packages, unmet dependency errors, or a candidate version that apt refuses to install. The useful takeaway is that Debian stable does not automatically chase the newest version; it requires intentional priority management. Most failures are resolved by correcting apt pinning priorities or repairing the dpkg state, not by forcing installation.

Common Causes and Diagnostic Signals

Cause	Diagnostic Signal	Typical Source
Low Pin-Priority for backports	Candidate version exists but priority is below the threshold for automatic selection	Missing or incorrect entry in /etc/apt/preferences.d/
Third-party repository conflict	External version has higher priority than the stable archive	Entry in /etc/apt/sources.list.d/ without a matching pin
Package held via apt-mark	dpkg -l shows an h flag; apt skips the upgrade	Manual apt-mark hold or automation
Broken dpkg state	dpkg --audit reports unconfigured or half-installed packages	Interrupted install, power loss, or stale lock

Ordered Diagnostic Checks

Run all commands in a terminal as root or prefix them with sudo. These checks are read-only and do not change system state.

Check 1: Inspect Package Policy and Candidate Versions

apt policy <package>

Replace <package> with the affected package name. Expected result: the output lists the installed version, the candidate version apt would install, and a priority table showing each source. Compare the candidate priority against the stable and backports entries. A priority of 100 means the version is installed or held at that level; 500 is the default for a normal archive; values below 100 are rarely selected automatically.

Check 2: List Upgradable and Held Packages

apt list --upgradable
dpkg -l | grep ^h

The first command shows every package apt considers an upgrade candidate. The second lists packages on hold. If a held package appears in the upgradable list but is skipped, the hold is blocking the change.

Check 3: Audit dpkg State

dpkg --audit

Expected result: no output indicates a clean database. Any output means packages are half-installed, half-configured, or awaiting triggers. Do not delete lock files under /var/lib/dpkg/ to clear this; confirm no apt process is running first, because removing locks on an active database can corrupt it.

Check 4: Review Repository and Pin Configuration

cat /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null
ls /etc/apt/preferences.d/

Confirm that security.debian.org entries are present and enabled. Look for suite names such as stable, stable-backports, or third-party hostnames. Then inspect any files under /etc/apt/preferences.d/ to see whether priorities are set intentionally or conflicting with the sources.

Fixes Matched to Findings

Finding: Low Pin-Priority for Backports

If apt policy shows the backports candidate with a priority too low for automatic selection, create a pin file. Run the following as root, replacing <codename> with the output of lsb_release -cs (for example, the current stable codename):

# /etc/apt/preferences.d/99-backports
Package: *
Pin: release n=<codename>-backports
Pin-Priority: 100

A priority of 100 makes backports available for manual installation without automatically replacing stable packages. Raising it to 500 or higher makes apt prefer backports automatically, which can increase churn and pull newer libraries into a stable system. Verify the suite name in your sources before saving.

Finding: Third-Party Repository Conflicts

If an external repository provides a higher or incompatible version, either disable the source by commenting its line in the relevant .list file, or lower its priority. As root, create a pin file using the repository hostname from your sources entry:

# /etc/apt/preferences.d/99-third-party
Package: *
Pin: origin "<repo-hostname>"
Pin-Priority: 100

After changing pins, run apt update and re-check apt policy <package>.

Finding: Packages Held with apt-mark

Remove the hold on the specific package:

apt-mark unhold <package>

Expected check: dpkg -l | grep ^h no longer lists the package.

Finding: Interrupted dpkg State

Repair the database in order. As root, first configure any pending packages:

dpkg --configure -a

Then attempt to fix broken dependencies:

apt --fix-broken install

Risk: if a package is half-configured, dpkg --configure -a may prompt for input or fail on a maintainer script error. Do not interrupt it. Avoid --force-overwrite or dpkg --force-all; these can create partial upgrades and break dependency chains on stable.

When to Escalate

Escalate to a distribution channel or system administrator when:

• Unmet dependencies persist after correcting pin priorities and repository sources.
• dpkg --audit or dpkg --configure -a reports database corruption, such as unreadable status files or lock errors that survive process checks.
• Multiple security updates remain stuck after holds are removed and dpkg state is clean.

Before reporting, capture a snapshot: save the output of apt policy <package>, dpkg --audit, dpkg -l | grep ^h, and copies of /etc/apt/sources.list and /etc/apt/preferences.d/ contents.

Limitations and Verification

Suite names, default priorities, and repository layouts can vary between Debian releases. Verify the exact backports suite name in your sources list rather than assuming a codename. Always simulate before applying changes:

apt full-upgrade --simulate

Expected result: the simulation completes without unmet dependency errors. After applying fixes, confirm success by re-running apt policy <package> to see the expected candidate and priority, checking that dpkg --audit returns no output, and reviewing apt list --upgradable to ensure only intentional packages remain.