Docker "error getting credentials": What It Means and How to Fix It
Docker error getting credentials means config.json points at a credential helper that is missing or failing. Fixes for Mac, Windows, WSL and Linux servers.
Docker's "error getting credentials" means your Docker client is configured to fetch registry passwords from a credential helper program, and that program is missing or failed when Docker called it. The fix is almost always in one file, ~/.docker/config.json: either install the helper it names, or point Docker at one that works on this machine.
Here is what the error usually looks like:
error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ``
You can hit it on docker pull, docker build (when a base image is pulled), docker compose up, or docker login. The login variant says "error storing credentials" or "error saving credentials" instead, but the cause is the same.
How Docker stores registry credentials
When you run docker login, the Docker CLI has to put your password or token somewhere. According to Docker's docker login reference, it has two options:
- A credential helper. A small external program named
docker-credential-<something>that hands the secret to your operating system's keychain. Docker calls it withget,storeoreraseevery time it needs a credential. - The config file itself. If no helper is configured, Docker writes the credentials into
config.jsonas base64. Base64 is an encoding, not encryption: anyone who can read the file can decode your password.
Which helper Docker uses is set by two keys in ~/.docker/config.json (%USERPROFILE%\.docker\config.json on Windows):
{
"credsStore": "desktop",
"credHelpers": {
"123456789012.dkr.ecr.eu-central-1.amazonaws.com": "ecr-login"
}
}
credsStoreis the default helper for every registry. The value is the program name without thedocker-credential-prefix, so"desktop"means "rundocker-credential-desktop".credHelpersoverrides the helper for specific registries.
The helper binary has to be on your $PATH. If it isn't, or it runs but fails, you get "error getting credentials".
Step 1: find which helper is failing
Read the error message. The name in quotes after exec: is the binary Docker tried to run. Then look at your config:
cat ~/.docker/config.json
And check whether that binary exists:
which docker-credential-desktop
The common helpers are:
| Value in config.json | Binary | Where it works |
|---|---|---|
desktop |
docker-credential-desktop |
Installed by Docker Desktop (Mac, Windows, Linux) |
osxkeychain |
docker-credential-osxkeychain |
macOS Keychain |
wincred |
docker-credential-wincred |
Windows Credential Manager |
pass |
docker-credential-pass |
Linux, GPG-encrypted files via pass |
secretservice |
docker-credential-secretservice |
Linux desktops with a D-Bus Secret Service (GNOME Keyring, KWallet) |
The last four come from the docker/docker-credential-helpers project.
The usual causes and their fixes
You uninstalled Docker Desktop, or switched to plain Docker Engine
Docker Desktop writes "credsStore": "desktop" into your config. If you later remove Desktop, or move to Docker Engine, Colima, OrbStack or Rancher Desktop, that line stays behind and points at a binary that no longer exists. This is the most common cause of the docker-credential-desktop version of the error.
Fix: change credsStore to a helper you actually have (for example osxkeychain on a Mac), or remove the line. Docker's docs say to log out before changing the store and log in again afterwards:
docker logout
# edit ~/.docker/config.json
docker login
On a Mac you can install the keychain helper with Homebrew (brew install docker-credential-helper) if it isn't already on your PATH.
WSL: the config points at a Windows binary
Inside WSL, the Linux side often ends up with "credsStore": "desktop.exe", which only works while Docker Desktop's WSL integration is enabled and the Windows binary is reachable from your Linux $PATH. If you turned off the integration, installed Docker Engine directly inside WSL, or your WSL PATH no longer includes Windows paths, the lookup fails.
Fix, in order of preference:
- If you use Docker Desktop, open Settings > Resources > WSL integration, enable it for your distro, and restart WSL with
wsl --shutdownfrom PowerShell. - If you run Docker Engine inside WSL without Desktop, remove the
credsStoreline from the WSL-side~/.docker/config.json, or set uppassas described below.
(New to WSL? See What Is WSL?.)
SSH or headless sessions
Credential helpers that talk to a desktop keychain need a desktop session. Over SSH, in cron, or in CI they often can't reach it:
- macOS over SSH: the keychain helper can't show an unlock prompt without a GUI session, and users report
User interaction is not allowed.in the error. Unlocking the login keychain first sometimes works:security unlock-keychain ~/Library/Keychains/login.keychain-db. Some people find the per-item access rules still block it; in that case log in once from a local terminal. - Linux servers with
secretservice: there is no D-Bus Secret Service on a headless server, so the helper fails. Switch topass, or to no helper at all (see the trade-off below).
(How to SSH into a server covers the basics of remote sessions.)
pass is installed but not initialized
docker-credential-pass needs a working pass store backed by a GPG key. Docker's Desktop for Linux docs describe the setup:
gpg --generate-key
# copy the key ID it prints, then:
pass init <your-gpg-key-id>
After that, docker login will store credentials as GPG-encrypted files. You'll be asked for the GPG passphrase when Docker needs them, which is a problem for unattended jobs unless you run a gpg-agent that caches it.
A registry-specific helper is missing
If the error names something like docker-credential-ecr-login or docker-credential-gcloud, the culprit is a credHelpers entry, often added by a cloud CLI. Install that cloud's helper, or remove the entry for registries you no longer use.
The quick fix, and what it costs
Many answers online say "delete the credsStore line". That does work: with no helper configured, Docker falls back to storing credentials in config.json. After removing it, run docker login again.
Understand the trade-off before doing this on a machine that matters. Your registry password or token will sit in ~/.docker/config.json as base64, which Docker's own docs call "less secure than configuring and using a credential store". Anything that can read your home directory, including a malicious package or script, can read it.
Reasonable ways to limit the damage if you go this route:
- Use an access token with the narrowest scope your registry supports (read-only if you only pull), not your account password.
- Keep the file private:
chmod 600 ~/.docker/config.json. - On CI, inject credentials per job from the CI's secret store and run
docker logoutat the end. (GitHub Actions secrets shows the pattern.)
On a personal laptop, the right fix is to get the OS keychain helper working. On a headless server, pass with a cached GPG key or a short-lived token with plain storage are both defensible; pick based on who else has access to the box.
Quick checklist
- Read the binary name in the error.
cat ~/.docker/config.jsonand look atcredsStoreandcredHelpers.which docker-credential-<name>to confirm it's missing.- Install the helper, switch to one that exists here, or remove the entry.
docker logoutthendocker login.- If you removed the helper, use a scoped token and
chmod 600the config.
If the next error is about the Docker socket rather than credentials, see Docker permission denied on the socket.
EasySpawn runs your projects on a persistent Linux server you reach over SSH or from a browser, so a credential setup you fix once stays fixed. See how it works or join the waitlist.
Related: What Is WSL? Running Linux on Windows, Explained · How to SSH Into a Server (Mac, Windows and Linux) · GitHub Actions Secrets: How to Store and Use Them Safely · Docker "Permission Denied While Trying to Connect to the Docker Daemon Socket": Fix
Keep reading
"exec format error" in Docker: ARM vs x86 Images Explained
exec format error almost always means a container image built for one CPU architecture (ARM, like Apple Silicon Macs) is running on another (x86/amd64 servers), or vice versa. How to check, build for the right platform with --platform and buildx, and the other cause: scripts without a shebang or with Windows line endings.
Docker "Port Is Already Allocated": How to Find and Free the Port
Docker can't publish a container's port because something on your machine already uses it — often another container, a local Postgres or a dev server. How to find what's using the port on Mac, Linux and Windows, stop it, or simply map the container to a different port.