This error occurs when a package's pre-installation script fails during apt install. Pre-installation scripts perform prerequisite checks before package installation, and failure typically indicates missing dependencies, corrupted packages, or system state issues.
When you run apt install, apt downloads the package and calls dpkg to handle installation. Before extracting files, dpkg runs a "pre-installation script" (.preinst) embedded in the package. This script checks system prerequisites, creates required users, or prepares the system for installation. When this script exits with status 1 (or non-zero), dpkg halts installation and reports this error. Exit status 1 is a generic failure—it could mean the script detected an unmet prerequisite, encountered a permission issue, or crashed due to an unexpected system state. The actual reason requires examining the package's pre-installation script or system logs. This differs from post-installation errors that occur after files are extracted. Pre-installation failures are usually easier to fix because the package hasn't modified your system yet. However, you need to diagnose why the script failed to choose the correct fix.
The first step is understanding why the script failed. The script file is stored in dpkg's info directory:
# Find the package name from the error message, then view its preinst script
sudo cat /var/lib/dpkg/info/<package-name>.preinstOr if the package isn't fully installed:
# List all .preinst files to find the right package
ls /var/lib/dpkg/info/*.preinst
# View the specific script
sudo cat /var/lib/dpkg/info/<package-name>.preinst | head -50Read the script carefully. Look for commands that might fail:
- getent passwd <username> - checks if system user exists
- mkdir /path - tries to create directories
- grep commands that search for configuration
- Commands checking for required packages or files
The script will have set -e at the top, meaning it exits on the first error. The failing command is your culprit.
dpkg logs the pre-installation script output in system logs. Check what actually failed:
# View dpkg installation log
sudo cat /var/log/dpkg.log | tail -50
# Or use journalctl for recent installations
sudo journalctl -u apt -n 50
# For detailed apt activity
sudo cat /var/log/apt/term.log | tail -100Look for error messages that explain why the script exited. Common patterns:
- "user already exists" - system user conflicts
- "no such file or directory" - missing prerequisites
- "permission denied" - insufficient privileges
- "command not found" - missing required tools
This usually tells you exactly what the script encountered.
Corrupted dpkg database often causes pre-installation script failures. Reconfigure all packages:
# Reconfigure all packages that may be in a broken state
sudo dpkg --configure -a
# Fix broken dependencies
sudo apt --fix-broken install
# Clean apt cache and update
sudo apt clean
sudo apt updateThe --configure -a flag tells dpkg to configure all unpacked but unconfigured packages. This often resolves issues from interrupted installations. After this, retry your installation:
sudo apt install <package-name>If it works, you're done. If not, move to the next step.
If configuration doesn't work, remove the problematic package completely and reinstall:
# Use force flags to remove even if broken
sudo dpkg --remove --force-remove-reinstreq <package-name>
# If that fails, use more aggressive flags
sudo dpkg --remove --force-all <package-name>
# Clean and update apt cache
sudo apt clean
sudo apt update
# Now try a fresh install
sudo apt install <package-name>The --force-remove-reinstreq flag removes the package even if it's in a broken state. This gives you a clean slate. Fresh installation from apt should work if the system is healthy.
If you identified the failing line in the preinst script (from Step 1), address it:
System user already exists:
# If the script tries to create user 'postgres' but it exists
sudo getent passwd postgres
# If output shows the user exists, you may need to adjust or remove it
# (Be careful with system users - only remove if safe)Missing required package:
# If script requires another package, install it first
sudo apt install <required-package>
# Then retry the original installation
sudo apt install <package-name>Missing directory:
# If script expects a directory like /var/lib/something
sudo mkdir -p /var/lib/something
sudo chmod 755 /var/lib/something
# Then retry
sudo apt install <package-name>Permission issues:
# Ensure dpkg can execute scripts
sudo chmod 755 /var/lib/dpkg/info/*.preinst
# Fix ownership of dpkg directories
sudo chown -R root:root /var/lib/dpkg
# Then retry
sudo apt install <package-name>For severe corruption, reset dpkg's package state. This is a more drastic step:
# Backup current dpkg status (always backup!)
sudo cp -r /var/lib/dpkg /var/lib/dpkg.backup
# List currently broken packages
dpkg --get-selections | grep "deinstall"
# For each broken package, force removal
sudo dpkg --remove --force-all <package-name>
# Reconfigure system
sudo dpkg --configure -a
# Update package lists
sudo apt clean
sudo apt update
sudo apt upgradeIf this doesn't work, you may have filesystem corruption or system-level issues. Check:
# Check filesystem for errors
sudo fsck -n /
# (read-only check, add -y flag to repair if needed)
# Check disk space
df -h
# Check inode availability
df -iFilesystem issues require running fsck from a live USB or single-user mode on Linux systems.
After applying fixes, verify your system is healthy before retrying:
# Check for missing dependencies
sudo apt check
# Try to fix any broken installs
sudo apt --fix-broken install
# Update package lists
sudo apt update
# Retry the installation that failed
sudo apt install <package-name>
# If successful, verify installation
dpkg -l | grep <package-name>If installation succeeds, the package is now properly installed. If you still encounter the same error after trying all steps, the package itself may be broken in the repository. Try:
# Check if an updated version exists
apt-cache policy <package-name>
# Try installing a different version
sudo apt install <package-name>=<version>
# Or report the issue to package maintainers
# Visit the package's bug tracker or Ubuntu launchpadUnderstanding dpkg Maintainer Scripts: dpkg supports four maintainer scripts executed at different stages: preinst (before file extraction), postinst (after extraction), prerm (before removal), and postrm (after removal). Each script is a shell script with set -e at the top, causing exit on first error. Pre-installation scripts are idempotent—they should be safe to run multiple times. If you need to debug, add set -x after the shebang to trace execution.
Exit Status Conventions: Exit status 0 means success. Non-zero (1, 2, 127, etc.) indicates failure. The specific number sometimes hints at the problem: status 127 means "command not found", status 2 often indicates argument errors, status 1 is a generic failure. Different packages define their own error codes in preinst scripts.
SELinux and AppArmor Interactions: Security modules like SELinux or AppArmor may prevent pre-installation scripts from executing certain operations. The script appears to fail, but the actual reason is security policy blocking file creation, user management, or process execution. Check with sudo semanage permissive -a dpkg_t on SELinux systems or AppArmor logs with sudo aa-logprof.
Filesystem Corruption Indicators: Pre-installation failures sometimes indicate filesystem issues before they become obvious. If multiple pre-installation scripts fail unpredictably or System.map errors appear, check filesystem integrity with fsck. Delayed allocation filesystems (ext4, btrfs, xfs) are vulnerable to corruption from unclean shutdowns—always shut down properly and run fsck if you encounter strange dpkg errors.
Race Conditions in Multi-User Systems: On systems with multiple users installing packages simultaneously, pre-installation scripts may fail due to race conditions. Package installation is designed to be single-threaded. If two apt or dpkg processes run concurrently, they interfere. Use sudo apt update followed by sudo apt install serially, never in parallel.
Recovering from Interrupted Installations: If installation is interrupted (network failure, system crash), dpkg enters an inconsistent state. The dpkg --configure -a command is specifically designed to resume configuration of interrupted installations. It reads the dpkg status database and resumes from where installation stopped.
Package Version Mismatches: Sometimes pre-installation script incompatibilities arise from installing newer packages on older systems or vice versa. A newer package's preinst might require system features not present on older OS versions. Check lsb_release -a for your OS version and verify the package's system requirements.
Testing Pre-installation Scripts Manually: To debug further, you can manually test the preinst script in a bash shell, though this requires understanding what dependencies it expects. Extract the script with ar -x <package.deb> and tar -xf data.tar.gz, then read and manually test critical commands. This is advanced and usually unnecessary—dpkg logs are usually sufficient.
dpkg: serious warning: files list file for package 'package-name' contains empty filename
How to fix "files list file contains empty filename" in APT
E: Sub-process /usr/bin/dpkg returned an error code (2)
How to fix "Sub-process /usr/bin/dpkg returned an error code (2)" in APT
dpkg-divert: error: rename involves overwriting 'path' with different file
How to fix dpkg-divert rename conflicts in APT
E: Sub-process /usr/bin/dpkg returned an error code (1) during kernel installation
How to fix "dpkg returned an error code (1)" in APT kernel installation
dpkg: dependency problems prevent configuration of triggers
dpkg: dependency problems prevent configuration of triggers in apt