Fix "Sub-process /usr/bin/dpkg returned an error code (1)"

Updated 5 min readIntermediateTested on Ubuntu 26.04 LTS, Ubuntu 24.04 LTS, Debian 13
Quick fix

Error code (1) is a generic failure. First retry the repair, then read the lines above the error to find the package that failed:

sudo dpkg --configure -a
sudo apt -f install
# still failing? show the real error:
sudo apt -f install 2>&1 | grep -B2 -A6 'dpkg: error'

Match the message you see to a cause below. The most common one on desktops is a driver module (DKMS) that fails to build for a new kernel.

What the error means

The last lines of a failed apt run look like this:

Errors were encountered while processing:
 nvidia-dkms-580
E: Sub-process /usr/bin/dpkg returned an error code (1)

apt hands the actual install to dpkg. When dpkg fails for any reason it exits with status 1, and apt reports that number. The line is the symptom, not the diagnosis. The useful information is the dpkg: error processing ... block further up and the package names under "Errors were encountered while processing". Everything below starts from that block.

Cause 1: a post-installation script failed

Setting up nvidia-dkms-580 (580.95.05-0ubuntu1) ...
Error! Bad return status for module build on kernel: 7.0.0-15-generic (x86_64)
Consult /var/lib/dkms/nvidia/580.95.05/build/make.log for more information.
dpkg: error processing package nvidia-dkms-580 (--configure):
 installed nvidia-dkms-580 package post-installation script subprocess returned error exit status 10

Every package can run a postinst script. If it exits non-zero, the package stays half-configured. The usual culprits:

  • DKMS modules (NVIDIA, VirtualBox, v4l2loopback, some Wi-Fi drivers) that do not compile against a new kernel. Read the make.log it names. Often a newer driver version supports the kernel: on Ubuntu run sudo ubuntu-drivers install to pick a supported driver, or remove the module package and reinstall a newer one. The Ubuntu NVIDIA drivers guide covers choosing a branch. Missing kernel headers also cause this: sudo apt install linux-headers-$(uname -r).
  • Services that fail to start during configuration, for example a web server or database with a broken config file or a port already in use. The message mentions invoke-rc.d or a systemctl failure. Check journalctl -xeu SERVICE, fix the config, then rerun sudo dpkg --configure -a.
  • initramfs or GRUB hooks failing during kernel updates, usually because /boot is full (see Cause 3).

To see exactly where a script fails, run it with tracing:

sudo sh -x /var/lib/dpkg/info/PACKAGE.postinst configure

Cause 2: two packages contain the same file

dpkg: error processing archive /var/cache/apt/archives/libfoo2_2.1-1_amd64.deb (--unpack):
 trying to overwrite '/usr/lib/x86_64-linux-gnu/libfoo.so.2', which is also in package libfoo-ppa 2.0-1

Typical after mixing a PPA or third-party repository with official packages. Prefer removing the package that should not be there:

sudo apt remove libfoo-ppa
sudo apt -f install

If both are needed and you accept that the new package's file wins, force this one overwrite:

Use force options on one package only

--force-overwrite silently replaces another package's file. Use it for the single .deb named in the error, never as a global dpkg option.

sudo dpkg -i --force-overwrite /var/cache/apt/archives/libfoo2_2.1-1_amd64.deb
sudo apt -f install

For PPAs, ppa-purge reverts every package from a PPA to the official version: sudo apt install ppa-purge && sudo ppa-purge ppa:owner/name.

Cause 3: no space left on / or /boot

dpkg: error processing archive ... (--unpack):
 cannot copy extracted data for './usr/lib/...' to '/usr/lib/....dpkg-new': failed to write (No space left on device)

Check free space and clean up:

df -h / /boot
sudo apt clean                 # removes downloaded .deb files
sudo apt autoremove --purge    # removes old kernels and unused packages

If autoremove cannot run because of the broken state, remove an old kernel directly with sudo dpkg --purge linux-image-VERSION-generic (never the one shown by uname -r). More options are on the "No space left on device" page.

Cause 4: dependency or interrupted-install problems

If the messages mention dependency problems - leaving unconfigured or the package depends on something that is not installed, the earlier failure is the root cause and the rest are knock-on errors: fix the first package listed and the others follow. If apt also says it cannot fix the dependencies, see "you have held broken packages". If the install was cut off part-way, see "dpkg was interrupted".

Cause 5: a corrupted download or dpkg database

dpkg-deb: error: archive '/var/cache/apt/archives/foo.deb' has premature member 'control.tar.zst'
dpkg: error processing archive ... (--unpack):
 dpkg-deb --control subprocess returned error exit status 2

A truncated .deb in the cache. Delete the cache and download again:

sudo apt clean
sudo apt update
sudo apt -f install

If dpkg complains about parsing file '/var/lib/dpkg/status', restore the automatic backup: sudo cp /var/backups/dpkg.status.0 /var/lib/dpkg/status, then run sudo dpkg --configure -a.

Last resort: remove the package that will not configure

If a package you do not need keeps failing (an abandoned driver, an old PPA tool), remove it even though it is half-installed:

sudo dpkg --remove --force-remove-reinstreq PACKAGE
sudo apt -f install
Do not do this to core packages

Never force-remove packages such as libc6, systemd, dpkg, apt or the running kernel. If one of those fails, fix the cause instead, from recovery mode if needed.

When removal also fails because the prerm or postrm script errors out, you can neutralise that script by moving it aside (sudo mv /var/lib/dpkg/info/PACKAGE.prerm /root/) and retrying the removal. Use this only for the package you are removing.

Distro-specific notes

  • Ubuntu 26.04 generates initramfs images with Dracut. A failure in dracut during a kernel update shows as a linux-image or dracut postinst error; it is almost always a full /boot or a broken DKMS module.
  • Debian 13 and Ubuntu 24.04 use initramfs-tools; the failing step is update-initramfs.
  • Linux Mint 22.3 behaves like Ubuntu 24.04; the Update Manager shows only "error code (1)", so run the commands in a terminal to see the details.
  • Fedora (DNF5) reports scriptlet failures as warnings ("Error in POSTIN scriptlet") and usually completes the transaction; check journalctl for the failed scriptlet. Arch reports error: command failed to execute correctly for failed hooks.

How to prevent it

  • Keep at least 300 MB free on /boot and run sudo apt autoremove after kernel updates.
  • Limit PPAs and third-party repositories, and remove ones you no longer use before a release upgrade.
  • Install drivers through ubuntu-drivers rather than vendor .run installers, so kernel updates rebuild them consistently.

Frequently asked questions

What does error code (1) actually mean?

Only that dpkg exited with a failure status. The real reason is printed above it, in the lines starting with dpkg: error processing. That earlier message is what you need to fix.

Is dpkg --force-overwrite safe?

It is acceptable for a one-off conflict between two packages that ship the same file, typically from a PPA. It replaces the other package's file, so remove the conflicting third-party package afterwards if you can.

How do I fix a package whose postinst script keeps failing?

Read the script at /var/lib/dpkg/info/PACKAGE.postinst, run it with sudo sh -x to see where it stops, and fix that cause. If the package is not needed, remove it with sudo dpkg --remove --force-remove-reinstreq PACKAGE.

Does sudo apt --fix-broken install fix error code 1?

Only when the cause is missing dependencies. If a script fails or files conflict, apt -f install hits the same error again until you fix that cause.

Spotted a mistake or a command that no longer works? Send a correction — pages are re-checked when reports come in.