Attempting to install new software, remove an obsolete utility, or run sudo apt upgrade in Ubuntu only for the terminal to abort with: “Sub-process /usr/bin/dpkg returned an error code (1)” is one of the most frustrating packaging errors in Debian-based Linux distributions. This error indicates that the low-level Debian package manager (dpkg) encountered a fatal failure while executing a package maintainer lifecycle script—most frequently a package’s post-installation (.postinst), pre-removal (.prerm), or configuration script located inside /var/lib/dpkg/info. When an installation script crashes due to broken dependencies, missing system users, altered file permissions, or Python environment mismatches, dpkg halts in a half-configured state, blocking all subsequent APT operations. This comprehensive troubleshooting guide explains step-by-step methods to identify the broken package, isolate faulty maintainer scripts, and restore APT package management in Ubuntu.
Understanding Why dpkg Returns Exit Code 1
To safely resolve dpkg exit code 1 without breaking system stability, you must identify which package failed and which specific script phase threw the error. Review the primary causes outlined below.
| Failure Point | Technical Rationale | Primary Diagnostic Step |
|---|---|---|
| Crashed Post-Installation Script (.postinst) | Package post-install script fails while starting a systemd daemon or creating users. | Inspect terminal error lines immediately preceding the error code 1 banner. |
| Corrupted dpkg Status Database | Unfinished package configuration leaves orphaned state entries in /var/lib/dpkg/status. |
Execute sudo dpkg --configure -a to force pending configurations. |
| Half-Installed Dependency Conflict | Upstream PPA packages overwrite shared library files owned by native Ubuntu packages. | Force dependency resolution using sudo apt install -f. |
| Corrupted Package Info Script in /var/lib/dpkg/info | Maintainer script syntax error prevents uninstallation or upgrading. | Temporarily move the specific package’s .postinst script to a backup directory. |
Step 1: Identify the Specific Problematic Package
The generic error banner “Sub-process /usr/bin/dpkg returned an error code (1)” appears at the very end of terminal output. To fix the issue, you must inspect the 5 to 10 lines directly above this message to locate the exact package name causing the failure.
- Scroll up in your Terminal window. Look for lines stating:
Setting up [packagename] ... dpkg: error processing package [packagename] (--configure): installed [packagename] package post-installation script subprocess returned error exit status 1 - Note the exact name of the problematic package (e.g.
mariadb-server,containerd, orlinux-image-generic).
Step 2: Force dpkg to Reconfigure Pending Packages
In many instances, packages were installed in an improper sequence during an interrupted update. Forcing dpkg to process its configuration queue resolves out-of-order dependency blocks.
- In Terminal, execute the configure-all command:
sudo dpkg --configure -a - If the command completes without errors, follow up immediately by repairing broken dependencies:
sudo apt install -f - If this resolves your issue, update your package lists to verify operational health:
sudo apt update && sudo apt upgrade -y
Step 3: Move Corrupted Maintainer Scripts in /var/lib/dpkg/info
If the error specifically states that the package’s post-installation script (.postinst) failed, the package maintainer’s configuration script contains a bug or failed daemon check. Bypassing this single script allows dpkg to mark the package as cleanly installed.
- Move all control scripts belonging to the problematic package into a temporary backup folder (substitute
[packagename]with your actual package name found in Step 1):sudo mv /var/lib/dpkg/info/[packagename].* /tmp/ - With the faulty script bypassed, command dpkg to complete configuration:
sudo dpkg --configure -a - Run the fix-broken install routine:
sudo apt install -f - Once configured successfully, reinstall the package properly or remove it cleanly:
sudo apt install --reinstall [packagename]
Step 4: Clean APT Cache and Purge Half-Installed Packages
If a package cannot be configured or repaired because its downloaded archive binary is incomplete or corrupted, purge the package completely from your system.
- Purge the broken package along with its configuration files:
sudo apt purge [packagename] - Clear your local APT package download archive cache:
sudo apt clean sudo apt autoclean - Refresh repository package lists:
sudo apt update - Your Ubuntu system will now install and upgrade packages smoothly without triggering dpkg error code 1.