The result you are building

Finished Result:

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.

Stop Before Proceeding:

Stop if the root filesystem is read-only, dpkg database files are physically corrupt, or the repair would remove the desktop/kernel/SSH path you depend on. Back up state and use recovery media or expert review.

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

  Start with the row that most closely matches the evidence. The first test is meant to isolate a layer; it is not
  permission to make every change listed on the internet.

    Evidence                  Likely layer       First decisive check            What the result means

    Interrupted               dpkg state         `sudo dpkg --audit`             Lists unpacked/half-configured packages;
    configuration                                                                resume configuration after storage and locks
                                                                                 are healthy.

    Unmet dependencies        APT solver         `apt-get -s -f install`         Simulation shows exact install/remove
                                                                                 proposal before any change.

    No installation           Sources            `apt-cache policy PKG` plus     Wrong release/component, stale mirror, or
    candidate/404                                source files                    disabled repository.

    Held back/conflicting     Pins/holds         `apt-mark showhold; apt-cache   A hold or higher-priority repository blocks the
    version                                      policy PKG`                     coherent set.

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.

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.

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.

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.

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.

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.

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

Starting Problem:

apt install reports a dependency requiring a newer library than Ubuntu offers.

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.

Proof Of Completion:

APT update/check are clean; no core packages are removed; requested supported package installs; source backup records the change.

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 What happened What it usually means Next safe move

Lock error persists A process still owns package state. Identify PID and wait/stop cleanly; never delete an active lock.

Maintainer script repeatedly fails Package-specific config/service action Inspect the first script error and package logs; is broken. fix its prerequisite.

Simulation removes many core Mixed release, pin, or repository Stop and repair sources/priority before packages conflict. applying.

No candidate after clean update Package/component/release does not Verify package name, enabled component, provide it. architecture, and supported source.

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
    Field                        Type               Requirement

    context                      object             Versioned environment, target, and requested outcome.

    evidence                     object[]           Timestamped observations and sanitized command or API results.

    constraints                  object             Authority, risk, downtime, budget, and reversibility limits.

    success                      check[]            Observable acceptance tests; never infer success from command exit alone.

  Returned output
    Field                        Type               Meaning

    diagnosis                    object             Likely layer, evidence, alternatives, and confidence.

    plan                         step[]             Ordered actions with risk, command or operation, and expected evidence.

    verification                 check[]            Pass/fail checks that prove the requested outcome.

    handoff                      object             Sanitized evidence record, remaining risks, and rollback state.

  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

APT and dpkg Repair Guide