APT and dpkg Repair Guide

Recover interrupted installations, dependency conflicts, held packages, and repository mismatches without damaging the dpkg database.

The result you're building

A healthy package state in which dpkg has no interrupted configuration, APT resolves one coherent repository set, the requested package installs or removes cleanly, and the exact repair is documented without deleting the package database.

Use this guide when

• APT reports broken dependencies, held packages, interrupted dpkg, repository errors, or a failed release upgrade.
• An install loop repeats without explaining which package/version conflicts.

Do not use it as a substitute for

• Do not delete /var/lib/dpkg, force-overwrite package files, or run random purge commands before preserving package and repository state.
• Do not continue when storage is read-only or reports I/O errors; recover the filesystem first.

Before you change anything

• Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
• Ubuntu release/architecture and current kernel.
• Complete apt/dpkg error beginning at the first failure.
• Configured source files and apt-cache policy for involved packages.
• Disk/inode capacity and pending/held package state.

Understand the system before fixing it

dpkg owns installed state; APT solves repository state
dpkg --configure -a resumes unpacked but unconfigured packages. apt-get -f install asks APT to resolve dependencies. They solve different layers and should be run only after reading the recorded error.

Candidate version explains most conflicts
Installed, candidate, and repository versions reveal mixed releases, third-party repos, pins, and phased/held updates.

Locks are protection, not clutter
A lock held by a live apt/dpkg process must not be removed. Identify the owner and wait or stop it cleanly.

Evidence-to-decision map

Step-by-step procedure

Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.

Step 01 — Preserve package evidence

Why: Package state changes on every attempted repair.

Do: Save dpkg audit, held packages, policy, sources, and the first error.

sudo dpkg --audit
apt-mark showhold
ps -ef | grep -E '[a]pt|[d]pkg'
df -h; df -i

Read the result: A live lock owner or storage fault becomes the first branch.

Next: Proceed only with healthy storage and no active package manager.

Step 02 — Refresh repository metadata

Why: Stale indexes can advertise versions no longer on the mirror.

Do: Validate source release names and keys, then run update once.

grep -RhsE '^[^#].*(deb |URIs:|Suites:)' /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null
sudo apt-get update
apt-cache policy PACKAGE

Read the result: 404/wrong Release errors identify the exact bad source; disable only that source if appropriate.

Next: Recheck package candidate versions.

Step 03 — Simulate the repair

Why: The solver may propose removing critical packages.

Do: Run configuration audit and a no-action fix simulation; inspect installs, upgrades, and removals.

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

Read the result: Abort if core desktop, kernel, network, or remote-access packages would be removed unexpectedly.

Next: Approve only a narrow coherent proposal.

Step 04 — Apply the narrow repair

Why: One controlled solver action is easier to verify and reverse than multiple purges.

Do: Run the reviewed fix, then configure pending packages. Handle the first maintainer-script error at its owning package.

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

Read the result: Repeated failure at the same package means inspect its script/log and dependencies; do not loop.

Next: Return to normal update/install test.

Step 05 — Verify consistency

Why: An install that exits zero can leave other packages broken.

Do: Run audit, dependency check, and the original install command; inspect service health if packages affected services.

sudo dpkg --audit
sudo apt-get check
apt-cache policy PACKAGE

Read the result: No audit output and no broken dependencies is the package-state gate.

Next: Record changed/removed packages and repo correction.

Step 06 — Prevent recurrence

Why: Mixed suites and abandoned third-party repositories reintroduce the conflict.

Do: Remove or correct the specific incompatible source/pin, keep one release family, and document holds intentionally.

Read the result: A future apt-get update must finish without source errors.

Next: Keep backup of source and preference files.

Worked example

Evidence collected

• apt-cache policy shows the target package candidate comes from a third-party repository for a newer Ubuntu release.
• Core libraries correctly come from Noble repositories.
• Repair simulation would upgrade/remove many base packages.

Decision: The repository suite is incompatible; forcing the dependency would mix releases.

Actions taken

• Disabled only the mismatched third-party source.
• Updated indexes and confirmed the candidate returned to the Ubuntu-supported version.
• Ran dpkg audit/check and installed the compatible package.

Why this example matters: Solver output prevented a dangerous forced install and identified the upstream configuration error.

Verify, recover, and hand off

Completion tests

• A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
• dpkg --audit produces no unresolved package state.
• apt-get check completes cleanly.
• apt-get update has no repository or signature error.
• The original package operation succeeds with reviewed changes only.
• Critical services still start and the current kernel remains installed.

Rollback or safe recovery

• Restore backed-up source/preference files if candidate selection becomes worse.
• Use package cache or official repository version to reinstall the one affected package; avoid mass downgrades without simulation.
• Boot a known-good kernel/recovery environment if package work breaks the normal boot path.

If the expected result does not appear

Reusable handoff record

• Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
• Package error and pre-repair audit/policy/sources.
• Solver simulation and approved change set.
• Repository/pin/hold correction with backup path.
• Post-repair audit/check and original install result.
• Packages removed/upgraded and service/kernel verification.

Agent delivery contract

Required inputs

Returned output

Agent refusal and escalation rules

• Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
• Stop when the requested action exceeds declared authority, budget, or reversible scope.
• Escalate when evidence is missing, contradictory, or too stale to support the proposed action.

Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.

Official reference starting points

• https://manpages.ubuntu.com/manpages/noble/en/man8/apt-get.8.html
• https://manpages.ubuntu.com/manpages/noble/en/man1/dpkg.1.html
• https://help.ubuntu.com/community/Repositories/Ubuntu