Fix 'gpg: keyserver receive failed: General error' When Adding GPG Key on Ubuntu/Debian

The Error

You're adding a third-party apt repository — Docker, Kubernetes, Spotify, whatever — and you run:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys ABCDEF1234567890

It hangs for 30–60 seconds, then dumps:

gpg: keyserver receive failed: General error

Sometimes the message is slightly different:

gpg: keyserver receive failed: No keyserver available
gpg: keyserver receive failed: Connection refused

Either way, your package installation is blocked. Here's how to get past it.

Root Causes

Each cause needs a different fix, so it's worth knowing which one you're dealing with:

Keyserver is down or unreachable — keyserver.ubuntu.com goes offline periodically, sometimes for hours
Port 11371 is blocked — your firewall, corporate proxy, or VPS provider blocks HKP port 11371 outbound
DNS resolution fails — the keyserver hostname doesn't resolve from your network
GPG version mismatch — older GPG versions have TLS handshake issues with modern keyservers
Deprecated apt-key workflow — Ubuntu 22.04+ deprecates apt-key adv entirely; it's the wrong tool

Fix 1: Switch to a Different Keyserver

Fastest option at 2 AM: try a different keyserver. The Ubuntu one is notoriously flaky. MIT and OpenPGP.org hold up better under load.

# Try MIT keyserver
sudo apt-key adv --keyserver hkp://pgp.mit.edu:80 --recv-keys YOUR_KEY_ID

# Or OpenPGP.org
sudo apt-key adv --keyserver hkp://keys.openpgp.org:80 --recv-keys YOUR_KEY_ID

# Or Ubuntu on port 80 (bypasses firewall blocking 11371)
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys YOUR_KEY_ID

That :80 suffix matters. It forces the connection over HTTP port 80 instead of HKP port 11371. On networks where 11371 is blocked, this alone fixes it.

Fix 2: Download the Key Directly via curl

Cut keyservers out of the equation. Most repository maintainers publish their GPG key at a direct URL — Docker, HashiCorp, GitHub CLI, all of them do. Grab it straight from the source:

# Method 1: curl into apt-key (older Ubuntu/Debian)
curl -fsSL https://example.com/repo-key.gpg | sudo apt-key add -

# Method 2: Modern approach (Ubuntu 22.04+)
curl -fsSL https://example.com/repo-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/repo-name.gpg

Then reference it in your sources.list entry:

echo "deb [signed-by=/usr/share/keyrings/repo-name.gpg] https://repo.example.com stable main" | sudo tee /etc/apt/sources.list.d/repo-name.list

Docker's official docs use this exact pattern:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Fix 3: Use gpg Directly with hkps://

When apt-key adv keeps choking, bypass it and call gpg directly with HTTPS keyserver support:

gpg --keyserver hkps://keys.openpgp.org --recv-keys YOUR_KEY_ID

Export the key and hand it to apt:

gpg --export YOUR_KEY_ID | sudo apt-key add -

# Or the modern way:
gpg --export YOUR_KEY_ID | sudo gpg --dearmor -o /usr/share/keyrings/repo-name.gpg

Fix 4: Behind a Corporate Proxy

Corporate networks with HTTP proxies are a common culprit. GPG's dirmngr daemon doesn't automatically pick up proxy settings — you have to configure it explicitly.

Add this to ~/.gnupg/dirmngr.conf:

keyserver hkps://keys.openpgp.org
honor-http-proxy

Then set the proxy env vars and restart dirmngr:

export http_proxy=http://proxy.company.com:3128
export https_proxy=http://proxy.company.com:3128

gpgconf --kill dirmngr
gpg --keyserver hkps://keys.openpgp.org --recv-keys YOUR_KEY_ID

Fix 5: Firewall Blocking All Keyserver Traffic

Some VPS providers — Oracle Cloud Free Tier and certain Hetzner configurations, for example — block all outbound traffic to keyserver ports by default. No keyserver will work from those machines.

Workaround: fetch the key on a machine that isn't locked down, then copy it over.

# On your LOCAL machine:
gpg --keyserver keyserver.ubuntu.com --recv-keys YOUR_KEY_ID
gpg --export --armor YOUR_KEY_ID > repo-key.asc
scp repo-key.asc user@your-server:/tmp/

# On the SERVER:
sudo apt-key add /tmp/repo-key.asc
# Or modern:
sudo gpg --dearmor -o /usr/share/keyrings/repo-name.gpg /tmp/repo-key.asc

Fix 6: Reinstall gnupg and dirmngr

Partial system upgrades and botched migrations can leave the GPG toolchain in a broken state — wrong permissions, stale socket files, corrupted keyring databases. A clean reinstall usually fixes it:

sudo apt-get remove --purge gpg gpg-agent dirmngr
sudo apt-get install gnupg2 gnupg-agent dirmngr

# Clear stale state
rm -rf ~/.gnupg
gpg --list-keys  # Recreates ~/.gnupg with correct permissions

After that, retry your original key import.

Verification

Once you've imported the key, confirm it's actually there:

# Old method
sudo apt-key list

# New method (Ubuntu 22.04+)
ls -la /usr/share/keyrings/
gpg --show-keys /usr/share/keyrings/repo-name.gpg

Run sudo apt update. Clean output looks like this — no NO_PUBKEY warnings, no GPG errors:

sudo apt update
# Expected: "Hit:" or "Get:" lines only

Prevention

Drop apt-key adv --keyserver from your playbooks and setup scripts. The keyserver workflow is deprecated in Ubuntu 22.04+ and unreliable everywhere. The replacement pattern is three steps:

Download the key from the repository's official URL using curl
Store it in /usr/share/keyrings/ via gpg --dearmor
Reference it explicitly with signed-by= in your sources.list entry

No keyserver dependency means it works in air-gapped environments, survives keyserver outages, and runs reliably in CI/CD pipelines where network access is restricted.