Skip to content

Raspberry Pi NetworkManager Update Failed: Diagnose and Repair APT

If a Raspberry Pi OS update fails with a network-manager error, start with the first specific error above APT's final summary. A download failure, a missing repository signature, and an interrupted package configuration need different repairs. Keep your current SSH session open and arrange local or alternate access before running a repair that might restart networking.

This guide covers package-update failures within an installed Raspberry Pi OS release. For Wi-Fi profiles, static addresses, and normal nmcli usage, see the NetworkManager configuration guide.

Raspberry Pi NetworkManager update error quick reference

Error or symptom Investigate first Appropriate next step
Temporary failure resolving DNS and the active connection Restore network access, then retry the package-index update.
Connection timeout Link, route, proxy, repository host Check the active route and the exact host reported by APT.
No space left on device Free bytes and inodes Free space deliberately before retrying the operation.
dpkg was interrupted Pending package configuration With recovery access ready, run dpkg --configure -a.
Unmet dependencies Installed/candidate versions, holds, repositories Simulate dependency repair and inspect the proposed changes.
post-installation script ... error Earlier script output and service journal Diagnose the script's reported cause; repeated reinstalls may reproduce it.
Missing Release file or signature error Repository configuration and clock Correct the identified source or time problem. Keep signature verification enabled.
Package-manager lock held Another running APT/dpkg process Wait for the legitimate operation to finish.

apt update refreshes package indexes; it does not install a new NetworkManager version. An error fetching an index is therefore a different stage from an error configuring a downloaded package. See the Debian APT reference.

1. Record the state before changing it

Run these on the Pi. They inspect state rather than replace profiles:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
cat /etc/os-release
dpkg --print-architecture
nmcli general status
nmcli device status
nmcli connection show --active
ip route
df -h / /var
df -i / /var
apt-cache policy network-manager
apt-mark showhold
sudo dpkg --audit

Then rerun the failing operation once and save its full output locally. A final Sub-process /usr/bin/dpkg returned an error code is a summary; the useful explanation usually precedes it. When asking for help, share the OS release, exact command, package version, and specific error, and redact credentials or private repository addresses.

2. Fix download failures before package repair

For a name-resolution error, use the repository hostname printed by APT:

1
2
3
4
5
# Replace the example with the host from the actual APT error.
getent hosts archive.raspberrypi.com
nmcli -f GENERAL,IP4,IP6 device show
ip route
timedatectl status

If the device is disconnected, recover its intended Ethernet or Wi-Fi profile using the networking guide. If it has an address but no usable route, investigate the gateway and upstream connection. If routing works but name lookup fails, inspect DNS supplied by the active profile. A failed ping alone is inconclusive because some networks block ICMP.

NetworkManager's connectivity-check command can provide another clue:

1
nmcli networking connectivity check

Its result depends on whether a probe is configured and reachable; it is not a substitute for testing the failing repository hostname. Once the network works, run sudo apt update and check that the affected source succeeds.

3. Resolve storage or repository errors

If storage is full, inspect both df -h and df -i. The latter detects exhausted inodes even when bytes remain. Identify files you can safely move or remove. sudo apt-get clean removes cached downloaded package files; it does not remove installed packages. Preserve logs until you have captured the failure.

For repository errors, inspect the release in /etc/os-release, the source files in /etc/apt/sources.list and /etc/apt/sources.list.d/, and apt-cache policy network-manager. Current source configuration can use .sources files as well as .list files. Do not change every source from Bookworm to Trixie to repair one package: a major OS migration is a separate operation. Use the migration guide if that is your actual goal.

4. Recover an interrupted package operation

First ensure no other package operation is still running:

1
ps -eo pid,comm,args | grep -E '[a]pt|[d]pkg'

Do not delete package-manager lock files while a process owns them. Once the interrupted operation is genuinely over, a reported pending-configuration problem can be repaired with:

1
sudo dpkg --configure -a

This executes package configuration scripts and can start or restart services. Arrange local or alternate access first if NetworkManager is one of the pending packages. The dpkg reference describes this operation.

For broken dependencies, preview the proposed repair:

1
sudo apt-get -s --fix-broken install

Inspect every proposed removal, downgrade, and installation. If the plan removes your network manager or requires a release change you did not intend, resolve the source/version problem before proceeding. When the plan is appropriate and recovery access is ready, run the same command without -s:

1
sudo apt-get --fix-broken install

If a configuration script fails again, read its specific output and journalctl -b -u NetworkManager --no-pager. Repair that cause before repeating the command.

5. Verify package state and a second SSH login

1
2
3
4
5
sudo dpkg --audit
dpkg-query -W -f='${Status}\n${Version}\n' network-manager
systemctl is-active NetworkManager
nmcli device status
nmcli connection show --active

Open a second SSH connection and test the required network access before closing your recovery session. For routine updates within the same release, continue with the official Raspberry Pi OS update procedure. Reboot when appropriate after checking that package configuration completed.

FAQ

Should I purge and reinstall NetworkManager?

Treat that as a deliberate recovery operation with local access, not the first response to an APT error. DNS, disk space, and repository failures are not fixed by removing the service that provides your connection.

Is --fix-missing the same as --fix-broken?

No. APT's missing-download handling and dependency repair address different conditions. Choose the operation from the actual error rather than combining switches from unrelated tutorials.

Why does Wi-Fi work while the upgrade fails?

A working connection does not prove that the package database, repository configuration, disk, or configuration scripts are healthy. Start with the reported failure stage.