Blog
6 min read

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:

  1. A credential helper. A small external program named docker-credential-<something> that hands the secret to your operating system's keychain. Docker calls it with get, store or erase every time it needs a credential.
  2. The config file itself. If no helper is configured, Docker writes the credentials into config.json as 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"
  }
}
  • credsStore is the default helper for every registry. The value is the program name without the docker-credential- prefix, so "desktop" means "run docker-credential-desktop".
  • credHelpers overrides 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:

  1. If you use Docker Desktop, open Settings > Resources > WSL integration, enable it for your distro, and restart WSL with wsl --shutdown from PowerShell.
  2. If you run Docker Engine inside WSL without Desktop, remove the credsStore line from the WSL-side ~/.docker/config.json, or set up pass as 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 to pass, 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 logout at 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

  1. Read the binary name in the error.
  2. cat ~/.docker/config.json and look at credsStore and credHelpers.
  3. which docker-credential-<name> to confirm it's missing.
  4. Install the helper, switch to one that exists here, or remove the entry.
  5. docker logout then docker login.
  6. If you removed the helper, use a scoped token and chmod 600 the 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