The Error
You run apt install nginx or apt upgrade and the terminal spits out:
dpkg: error processing package nginx (--configure)
dpkg: dependency problems prevent configuration of nginx
Errors were encountered while processing:
nginx
Now apt is half-broken. Every subsequent apt install or apt upgrade throws the same error. Welcome to dpkg hell.
What's Actually Happening
dpkg — the low-level package manager underneath apt — tried to configure a package after extracting it, but hit a wall. Usually it's one of these:
- A dependency is missing, the wrong version, or itself broken
- A previous install or upgrade was interrupted mid-way (power cut, Ctrl+C, SSH drop)
- A post-installation script (
postinst) crashed or exited with a non-zero code - Conflicting packages are blocking configuration
- The package database itself is in an inconsistent state
One stuck package freezes the entire apt system. Nothing installs or upgrades until you fix the broken state first.
Fix It — Work Through These in Order
Step 1: Force-configure pending packages
Start here. This tells dpkg to finish configuring whatever it left half-done:
sudo dpkg --configure -a
No errors? Good. Follow up immediately with:
sudo apt install -f
The -f flag stands for "fix broken" — apt scans for unmet dependencies and resolves them automatically. Run apt upgrade after to confirm the system is clean.
Step 2: Fix broken dependencies
Still broken? Let apt try to heal itself:
sudo apt --fix-broken install
sudo apt autoremove
sudo apt autoclean
Then retry the original install:
sudo apt install nginx
Step 3: Remove and reinstall the broken package
Sometimes the only way out is to yank the broken package and start fresh:
# Purge the package (removes config files too)
sudo dpkg --purge nginx
# Or just remove without touching configs
sudo dpkg --remove nginx
# Clean up any remaining breakage
sudo apt install -f
# Reinstall
sudo apt install nginx
If dpkg --purge itself chokes on a script error, force it through:
sudo dpkg --purge --force-remove-reinstreq nginx
Step 4: Handle dependency conflicts manually
When the error calls out a specific dependency by name, go after it directly:
# Grep the full error output for the dependency chain
sudo apt install nginx 2>&1 | grep "Depends"
# Install the missing dependency explicitly
sudo apt install libssl1.1
# Then retry
sudo apt install nginx
Version conflicts are trickier. Check what's actually available, then pin a working version:
# See all available versions
apt-cache policy nginx
# Install a specific version
sudo apt install nginx=1.18.0-0ubuntu1.4
Step 5: Clear the package cache and refresh
Stale or half-downloaded .deb files cause silent failures that are easy to miss. Wipe them:
sudo apt clean
sudo apt update
sudo apt install nginx
Step 6: Nuclear option — rebuild the dpkg database
Last resort. The dpkg status database can corrupt after a disk error or hard reboot mid-upgrade. Back up first, then clean the stale lock files:
# Backup the status database
sudo cp /var/lib/dpkg/status /var/lib/dpkg/status.bak
# Remove stale lock files from a stuck previous run
sudo rm -f /var/lib/dpkg/lock-frontend
sudo rm -f /var/lib/dpkg/lock
sudo rm -f /var/cache/apt/archives/lock
sudo rm -f /var/lib/apt/lists/lock
# Reconfigure everything
sudo dpkg --configure -a
sudo apt install -f
sudo apt update && sudo apt upgrade
Important: Only delete lock files if you're certain no apt or dpkg process is running. Verify first: ps aux | grep -E 'apt|dpkg'
Verify the Fix
Before calling it done, run a quick sanity check:
# Look for any packages still in a broken state
sudo dpkg --audit
# List packages with bad status flags (rc, iF, iU, rF)
dpkg -l | grep -E '^(rc|iF|iU|rF)'
# If both commands return nothing, you're clean
# Confirm with a full upgrade
sudo apt update && sudo apt upgrade
A healthy system returns no output from dpkg --audit. That's your green light.
Specific Scenario: postinst Script Failing
See postinst mentioned in the error? The package extracted fine — it failed during setup. Classic culprits: a service couldn't start because port 80 is already taken, or a config file has a syntax error.
# Check what's sitting on port 80 (for nginx)
sudo ss -tlnp | grep :80
# Check the service status for clues
sudo systemctl status nginx
# Read the postinst script to understand what it's trying to do
cat /var/lib/dpkg/info/nginx.postinst
Kill the conflicting service or fix the config, then finish the configuration manually: sudo dpkg --configure nginx.
Prevention
- Never Ctrl+C during apt operations — if you absolutely must stop, wait for the current package to finish first
- Be selective with PPAs — third-party PPAs are the single biggest source of dependency conflicts on Ubuntu; each one you add is a potential liability
- Update regularly — running
sudo apt update && sudo apt upgradeweekly keeps the dependency gap small; skipping six months of updates and then upgrading is a recipe for conflicts - Use
apt, notdpkg, for installs — apt resolves dependencies automatically; dpkg just blindly extracts the package - Watch your disk space — a full
/varpartition causes dpkg to fail mid-write, leaving packages half-installed; check it before any large upgrade:df -h /var
If you manage servers with Ansible or cloud-init, bad YAML config is another way installs go sideways before dpkg even gets involved. ToolCraft's YAML ↔ JSON Converter lets you validate YAML syntax in the browser without uploading anything — handy for catching typos before they hit the server.