dpkg returned an error code, explained and fixed

When an install or upgrade on Debian or Ubuntu ends with E: Sub-process /usr/bin/dpkg returned an error code (1), that line is only the summary. It says “a package operation failed”, and the actual reason was printed earlier in the same output: a named package whose configuration or install script failed, a disk that filled mid-operation, or a dependency state that cannot resolve. Fixing dpkg starts with scrolling up, not with the summary line. The package named in the lines above is where the repair happens.

Read the real error first

  1. Re-run or scroll to find the first failure: messages like “Errors were encountered while processing: <package>” and the lines just before them state the cause, commonly a maintainer script returning an error, a service that would not start during configuration, or “No space left on device”.
  2. Check disk space before anything clever: df -h with attention to / and a separate /boot, which fills with old kernels on long-lived systems and blocks kernel package configuration. A full disk manufactures this error for innocent packages.

The standard repair sequence

  1. Let the package manager finish pending work: sudo dpkg --configure -a retries configuration of unpacked-but-unconfigured packages, then sudo apt --fix-broken install resolves broken dependencies. This pair resolves the majority of cases once the underlying blocker (space, a stopped service) is cleared.
  2. Address the named package's specific complaint: if its script failed because a service could not start, fix or temporarily satisfy that service; if it failed on a file conflict with another package, the output names both, and removing the conflicting (usually older or third-party) package is the route.
  3. As a later resort, remove the stuck package (sudo apt remove <package>, or sudo dpkg --remove --force-remove-reinstreq <package> when apt cannot), then reinstall it fresh once the system is consistent. Force options come after the standard sequence, not before.
Do not delete dpkg's lock files or the dpkg status database to “unstick” it. The locks are not the disease (see the separate lock page), and editing /var/lib/dpkg/status by hand can corrupt the package record. Every legitimate repair goes through dpkg and apt themselves.

Common questions

Why does every subsequent install fail too? dpkg stops in a half-configured state and apt refuses to proceed until the pending configuration completes. That is protective, and it is why the repair sequence starts with --configure -a rather than retrying the original install.

The failing package is a kernel, is that special? Mostly in one way: its configuration needs space in /boot and it builds an initramfs, so a full /boot or a failing initramfs tool is the usual root cause. Free space (remove old kernels with sudo apt autoremove once things work) and retry.

A third-party .deb caused it, what now? Packages from outside the repositories can ship scripts that assume services or paths your system lacks. Remove that package, confirm apt is healthy again (a simple install succeeds), then decide whether the vendor has a version suited to your release.

Related errors

Unable to acquire the dpkg lock · Kernel panic: not syncing · No such file or directory