APT failures are common on long-lived Ubuntu machines, and they usually appear after a release upgrade, a third-party repository change, a removed PPA, a manually installed .deb, or an interrupted package installation.
The error message can look dramatic, but most APT problems are not mysterious — they are state problems where APT's view of repositories, versions, and installed packages no longer agrees.
APT is trying to answer four questions:
- Which repositories are enabled?
- Which package versions are available?
- Which packages are already installed?
- Which package changes are allowed?
When those answers conflict, you get held packages, broken dependencies, missing public keys, bad PPA errors, or packages kept back during upgrade. This guide gives you a practical troubleshooting sequence for Ubuntu APT, written for developers, DevOps engineers, and Linux users who want to fix the system without blindly pasting random commands from forum threads. Pair it with our collection for related Linux workflows.
The Short Version
If your system is only mildly broken, start here:
sudo apt update
sudo dpkg --configure -a
sudo apt --fix-broken install
sudo apt update
sudo apt upgrade
If packages are kept back:
apt list --upgradable
apt-mark showhold
sudo apt full-upgrade
If a PPA or third-party repository is failing:
ls /etc/apt/sources.list.d/
sudo apt update
Read the failing repository line, then disable or fix that repository. If you see NO_PUBKEY, do not blindly import random keys from a keyserver — find the official repository instructions, install the repository key into /etc/apt/keyrings, and bind it to that repository with signed-by.
Before You Fix Anything: Read the APT Error First
Run this first:
sudo apt update
Do not skip it. apt update refreshes package metadata. It does not upgrade packages. It tells you whether Ubuntu can read all configured repositories and verify their metadata.
Then check your Ubuntu version and codename — a stale release name in /etc/apt/sources.list.d/ is a frequent cause of 404 and Release file errors. If you are unsure which release you are on, see walks through adding vendor repositories with signed-by from the start.
Do not just edit the codename and hope for the best — some repositories do not publish packages for every Ubuntu version, so verify vendor support for your release first.
Fixing GPG and NO_PUBKEY Errors
What NO_PUBKEY Means
APT repositories publish signed metadata, and your machine needs the matching public key to verify that metadata. If the key is missing, APT refuses to trust the repository, which is the behavior you want — do not disable signature checks just to make the error disappear.
The Modern Keyring Pattern
Create the keyring directory:
sudo install -d -m 0755 /etc/apt/keyrings
Download and dearmor the vendor key:
curl -fsSL https://example.com/repository-key.gpg \
| sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
Set readable permissions:
sudo chmod 0644 /etc/apt/keyrings/example.gpg
Add the repository with signed-by:
echo "deb [signed-by=/etc/apt/keyrings/example.gpg] https://example.com/linux/ubuntu noble stable" \
| sudo tee /etc/apt/sources.list.d/example.list
Then update:
sudo apt update
Replace noble with your Ubuntu codename if needed:
. /etc/os-release
echo "$VERSION_CODENAME"
Why apt-key Is the Wrong Habit
Old guides often use:
curl -fsSL https://example.com/key.gpg | sudo apt-key add -
Avoid apt-key add for new setups. The old apt-key style adds keys to a broad trust area, which makes it harder to reason about which key is trusted for which repository, whereas the modern signed-by style scopes the key to a specific repository and is basic supply-chain hygiene.
Find Legacy Trusted Keys
You may still have old keys in:
/etc/apt/trusted.gpg
/etc/apt/trusted.gpg.d/
List files:
ls -l /etc/apt/trusted.gpg.d/
Do not delete keys randomly — first map each key to a repository, then migrate one repository at a time to /etc/apt/keyrings and signed-by.
Common GPG Mistakes
Do not use random keyservers as your first choice when fixing NO_PUBKEY errors.
Better order:
- Use the vendor's official install documentation.
- Download the key from the vendor's official HTTPS URL.
- Store it in
/etc/apt/keyrings. - Bind it with
signed-by. - Run
sudo apt update.
Avoid these shortcuts:
sudo apt update --allow-unauthenticated
sudo apt install --allow-unauthenticated package-name
They may work temporarily, but they remove the signature verification that protects you from tampered repository metadata.
Fixing "The Repository Is Not Signed"
This error usually means one of these things:
- The repository does not publish signed metadata.
- The repository URL is wrong.
- The repository no longer supports your Ubuntu version.
- A proxy or mirror is returning the wrong content.
- You are using HTTP where the vendor now expects HTTPS.
- The source file has the wrong suite or component.
Find the failing source:
sudo apt update
APT will print the URL. Then search for it:
grep -R "example.com" /etc/apt/sources.list /etc/apt/sources.list.d/
Disable it temporarily:
sudo mv /etc/apt/sources.list.d/example.list /etc/apt/sources.list.d/example.list.disabled
sudo apt update
If APT works again after disabling the file, reinstall that repository from the vendor's current official instructions rather than re-enabling the old configuration.
Fixing Duplicate Repository Warnings
APT may warn that a target is configured multiple times.
List matching entries:
grep -R "repo-url-or-domain" /etc/apt/sources.list /etc/apt/sources.list.d/
Duplicate repositories often appear after running vendor install scripts multiple times.
Keep one source file. Disable the others:
sudo mv /etc/apt/sources.list.d/duplicate.list /etc/apt/sources.list.d/duplicate.list.disabled
sudo apt update
Duplicate warnings are not always fatal, but they are a sign of sloppy configuration, so keep one source file and disable the duplicates.
Fixing Packages from the Wrong Ubuntu Release
One of the worst APT problems is mixing Ubuntu releases — for example, a machine on Ubuntu 24.04 should not casually pull packages from Ubuntu 22.04 or Debian testing. Sometimes it works for a while, but eventually the dependency graph becomes a puzzle that APT cannot solve cleanly.
Check your release:
. /etc/os-release
echo "$VERSION_CODENAME"
Search sources:
grep -R "^deb" /etc/apt/sources.list /etc/apt/sources.list.d/
Look for foreign codenames in the enabled sources, then inspect the affected package:
apt-cache policy package-name
If the installed version came from an old or foreign repository, disable that repository and downgrade or reinstall the affected package from Ubuntu repositories.
A conservative repair path is:
sudo apt update
sudo apt install --reinstall package-name
For deeper conflicts, you may need to remove the package and reinstall it from the correct source rather than forcing an upgrade over a foreign version.
Cleaning APT Cache and Unused Packages
APT cache cleanup is not a dependency fix on its own, but it can help after many failed installs by reclaiming disk space and clearing stale package files.
Remove packages that were installed automatically and are no longer needed:
sudo apt autoremove
Clean downloaded package files:
sudo apt clean
Or remove only obsolete package files:
sudo apt autoclean
Use autoremove carefully on servers and desktops with manually installed driver stacks, and read the removal list before accepting.
Practical APT Troubleshooting Recipes
Recipe: Package Is Kept Back
sudo apt update
apt list --upgradable
apt-mark showhold
sudo apt full-upgrade
If APT proposes reasonable changes after simulation, accept them. If it proposes large removals, stop and inspect:
apt-cache policy package-name
Recipe: Held Package Blocks Upgrade
apt-mark showhold
apt-cache policy package-name
sudo apt-mark unhold package-name
sudo apt upgrade
Only unhold a package if the hold is no longer intentional, because removing a hold that protects production software can trigger a breaking upgrade.
Recipe: Interrupted Install
sudo dpkg --configure -a
sudo apt --fix-broken install
sudo apt upgrade
Recipe: NO_PUBKEY Error
- Identify the repository from
sudo apt update. - Find the vendor's current official install instructions.
- Install the key into
/etc/apt/keyrings. - Use
signed-byin the source file. - Run
sudo apt update.
Example structure:
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://example.com/key.gpg \
| sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
sudo chmod 0644 /etc/apt/keyrings/example.gpg
echo "deb [signed-by=/etc/apt/keyrings/example.gpg] https://example.com/ubuntu noble main" \
| sudo tee /etc/apt/sources.list.d/example.list
sudo apt update
Recipe: PPA Does Not Have a Release File
sudo apt update
ls /etc/apt/sources.list.d/
grep -R "ppa.launchpadcontent.net\|launchpad" /etc/apt/sources.list.d/
Disable the PPA:
sudo mv /etc/apt/sources.list.d/example.list /etc/apt/sources.list.d/example.list.disabled
sudo apt update
Then decide whether to remove, replace, or purge packages from that PPA.
Recipe: Manual .deb Broke Dependencies
dpkg -l | grep package-name
apt-cache policy package-name
sudo apt remove package-name
sudo apt --fix-broken install
If you still need the software, prefer the vendor's current APT repository over repeated manual .deb installs, which tend to accumulate dependency conflicts over time.
Essential APT Troubleshooting Commands
Repository and Metadata
sudo apt update
grep -R "^deb" /etc/apt/sources.list /etc/apt/sources.list.d/
ls /etc/apt/sources.list.d/
Package State
apt list --installed
apt list --upgradable
apt-mark showhold
dpkg -l | grep package-name
Package Policy and Dependencies
apt-cache policy package-name
apt-cache depends package-name
apt-cache rdepends package-name
Repair
sudo dpkg --configure -a
sudo apt --fix-broken install
sudo apt install --reinstall package-name
sudo apt full-upgrade
Cleanup
sudo apt autoremove
sudo apt autoclean
sudo apt clean
Simulation
apt -s install package-name
apt -s full-upgrade
What Not To Do
Do Not Randomly Delete /var/lib/dpkg
If you see advice to delete dpkg state files, be skeptical. The dpkg database is the record of installed packages, and deleting pieces of it can turn a repairable package issue into a full system recovery project.
Do Not Disable Signature Verification
Avoid:
--allow-unauthenticated
If a repository cannot be verified, fix the key or disable the repository rather than bypassing authentication.
Do Not Mix Ubuntu Releases Casually
Do not add repositories for another Ubuntu release unless you understand APT pinning and the dependency consequences.
This applies especially to:
- desktop environments
- graphics drivers
- Python stacks
- container runtimes
- Kubernetes packages
- database packages
Do Not Treat PPAs as Harmless
PPAs are useful, but they are still package repositories that can replace libraries and system packages — which may be exactly what you want, or exactly why your next upgrade breaks. Prefer PPAs for specific applications, not for broad system foundations, unless you trust the maintainer and understand the upgrade path.
APT Troubleshooting Decision Tree
Use this mental model:
flowchart TD
A["Does sudo apt update fail?"] -->|yes| B["Fix repositories, GPG keys, PPAs, network, or release files"]
A -->|no| C["Did an install or upgrade get interrupted?"]
C -->|yes| D["Run dpkg --configure -a, then apt --fix-broken install"]
C -->|no| E["Are packages held?"]
E -->|yes| F["Inspect apt-mark showhold and decide whether to unhold"]
E -->|no| G["Are packages kept back?"]
G -->|yes| H["Inspect apt full-upgrade simulation and package policy"]
G -->|no| I["Is a third-party source involved?"]
I -->|yes| J["Inspect apt-cache policy and source files"]
I -->|no| K["Inspect the specific package dependency error"]
Most APT problems become manageable once you stop treating them as one big error and start separating repository health, package state, dependency solving, and trust configuration — the decision tree above is a shorthand for that discipline.
Recommended Baseline for Developer Machines
For a clean Ubuntu developer workstation, I prefer this baseline:
- Keep Ubuntu repositories standard.
- Use vendor APT repositories only when they are official and maintained.
- Use
/etc/apt/keyringsandsigned-byfor third-party repositories. - Avoid old
apt-keyinstructions. - Avoid mixing PPAs that replace core system libraries.
- Use containers,
uv,pipx,asdf,mise, or language-native tools for fast-moving developer dependencies. - Keep APT responsible for the operating system, drivers, services, and stable CLI tools.
For desktop software, prefer Flatpak or Snap over PPAs when a sandboxed universal package fits your needs. APT is excellent when it manages the base system, but it becomes painful when it is forced to behave like a universal developer dependency manager for fast-moving language ecosystems.
Final APT Troubleshooting Checklist
When APT is broken on Ubuntu, work through this checklist:
[ ] Run sudo apt update and read the first real error.
[ ] Check Ubuntu codename with /etc/os-release.
[ ] Finish interrupted installs with dpkg --configure -a.
[ ] Repair dependencies with apt --fix-broken install.
[ ] Check held packages with apt-mark showhold.
[ ] Inspect package versions with apt-cache policy.
[ ] Disable broken PPAs or third-party repositories.
[ ] Replace apt-key style repositories with signed-by keyrings.
[ ] Simulate risky operations with apt -s.
[ ] Read removals before accepting full-upgrade or autoremove.
APT is not fragile, but it is strict, and that strictness is a feature: it prevents unsigned repositories, impossible dependency sets, and accidental package replacements from silently changing your system. The calm way to fix APT is to preserve that strictness, find the conflicting state, and repair the smallest thing that is actually wrong.
SOCIAL SHARE CARD GENERATOR