Overview

Sub-process /usr/bin/dpkg returned an error code (1) is apt’s generic report that the dpkg it called underneath exited non-zero:

Setting up example-agent (2.4.1-1) ...
Job for example-agent.service failed because the control process exited with error code.
dpkg: error processing package example-agent (--configure):
 installed example-agent package post-installation script subprocess returned error exit status 1
Errors were encountered while processing:
 example-agent
E: Sub-process /usr/bin/dpkg returned an error code (1)

The key point: this last line is not the real error. It’s a wrapper. The actual failure is printed above it — a maintainer script (postinst/preinst) that failed, a broken config, or a package left half-configured. On Debian/Ubuntu the fix is always the same shape: scroll up, find the package and the real message, fix that, then let dpkg finish configuring.

Symptoms

apt-get install, upgrade, or dpkg -i ends with E: Sub-process /usr/bin/dpkg returned an error code (1).
Just above it: dpkg: error processing package <name> (--configure): ... subprocess returned error exit status 1.
Re-running the command reports the same package is still not configured.
dpkg -l shows the package in state iF (half-configured) or iU (unpacked, not configured).
Frequently seen when a package’s postinst tries to start a service that won’t come up.

Common Root Causes

The most common cause is a maintainer-script failure — the package’s postinst/preinst ran a command that exited non-zero (a service that fails to start, a missing dependency at runtime, a bad config it tried to generate). Other causes:

A service the postinst starts fails (bad config file, port in use, missing directory), so the script returns 1.
A prior interrupted install left the package half-configured, and every apt run trips over it.
Disk full or a read-only /var so the script can’t write.
A dependency that is unpacked but not yet configured, so the script’s assumptions fail.
A genuinely buggy or third-party package whose script errors on your specific OS version.

How to diagnose

Scroll up and read the real error. The Sub-process ... (1) line is the symptom; the cause is the dpkg: error processing package <name> block above it. Note the exact package name and the last command it ran.

Identify every package dpkg couldn’t configure:

sudo dpkg --audit
dpkg -l | grep -E '^.[^i]|^iF|^iU'

Read the failing maintainer script to see what it actually does:

ls -l /var/lib/dpkg/info/example-agent.*
cat /var/lib/dpkg/info/example-agent.postinst

If the postinst starts a service, get the real reason it failed:

systemctl status example-agent.service --no-pager
journalctl -u example-agent.service --no-pager -n 50

Rule out the boring causes — a full disk or read-only filesystem makes scripts fail with a misleading (1):
```
df -h /var /
mount | grep -E ' / | /var '
```

Fixes

Re-run configuration once the underlying cause is fixed (safest, resolves most cases):
```
sudo dpkg --configure -a
```

Let apt repair a half-broken state:

sudo apt-get --fix-broken install
sudo apt-get -f install

Fix the actual maintainer-script cause you found. If the postinst failed starting a service, correct its config/port/permissions, then reconfigure just that package:
```
sudo dpkg-reconfigure example-agent
# or re-attempt configure for the one package
sudo dpkg --configure example-agent
```
Reinstall the package if its scripts or files are damaged:
```
sudo apt-get install --reinstall example-agent
```
Free space or remount read-write if that was the cause, then re-run dpkg --configure -a:
```
sudo apt-get clean
df -h /var
```
Last resort — remove a package whose scripts refuse to complete so the rest of the system can update. Only after you’ve read the real error and accepted losing that package:
```
sudo dpkg --remove --force-remove-reinstreq example-agent
sudo apt-get -f install
```

Warning: Do not lead with --force-* flags. Forcing past a maintainer-script failure can leave the system in a worse, half-removed state. Read the real error above the Sub-process line first; forcing is the last step, not the first.

What to watch out for

The (1) line tells you nothing on its own — the diagnostic value is entirely in the lines above it. Always capture full apt output, not just the last line.
A single stuck package blocks every future apt operation until it configures or is removed; fix it before it snowballs.
dpkg-reconfigure and reinstall re-run the same scripts — if the root cause (bad config, dead service) isn’t fixed, they’ll fail identically.
On RHEL/Rocky/Alma the analog is an rpm %post scriptlet failure reported as Error in POSTIN scriptlet; the same “read the scriptlet, fix the real cause” approach applies.

Want faster Linux incident response? Use DevOps AI Toolkit to turn production errors into clear diagnostics, remediation steps, and reusable runbooks.

Linux Error: 'Sub-process /usr/bin/dpkg returned an error code (1)' — Cause, Fix, and Troubleshooting Guide

Fixing errors like this? Get 500 free DevOps AI prompts