Photo by Ferenc Almasi on Unsplash

So there I was, 11pm, trying to push a container image before a deployment window, and Docker just... refused. Threw this at me:

error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ``

No warning, no obvious reason. The image built fine. The tag looked right. Docker just decided tonight wasn't the night. If you've landed here, you've probably seen some variation of that error — maybe it's docker-credential-osxkeychain on a Mac, or docker-credential-wincred on Windows. Same problem, different flavor.

Here's what's actually going on and how to fix it without losing your mind.

Why This Error Happens

Docker stores your login credentials using a "credential helper" — basically a small external binary it hands off authentication to. On Docker Desktop for Mac, that's docker-credential-osxkeychain. On Windows, it's docker-credential-wincred. The problem is your ~/.docker/config.json still references one of these helpers even when the binary isn't installed, isn't in your PATH, or got orphaned after a Docker Desktop update or uninstall.

I've seen this happen a hundred times after someone switches from Docker Desktop to a manual Docker Engine install on Linux, or after a fresh OS reinstall where Docker Desktop didn't come along for the ride. The config file survived. The credential helper didn't.

Here's what the problematic config.json typically looks like:

{
  "credsStore": "desktop",
  "currentContext": "default"
}

That credsStore key is the culprit. Docker sees it, goes looking for the docker-credential-desktop binary, finds nothing, and throws the error.

Fix 1: Edit the Config File Directly (The Quick One)

This is the fastest fix and honestly works 80% of the time. Open your Docker config file:

nano ~/.docker/config.json

Find the credsStore line and either remove it entirely or change it to an empty string. Your file should look something like this after:

{
  "auths": {}
}

Save it, then try your docker login or docker push again. If you weren't already logged in, you'll need to re-authenticate:

docker login

It'll prompt for your username and password and store the credentials as a base64-encoded string right in the config file instead of offloading to an external helper. Not the most secure option long-term, but it works, and for a dev environment or CI pipeline, it's completely fine.

Fix 2: Install the Missing Credential Helper

If you actually want the credential store working properly — which is the right call for anything beyond a personal dev setup — you need to install the binary Docker is looking for.

On Linux, the most common one is docker-credential-pass. Here's how to get it:

# Download the latest release
curl -fsSL https://github.com/docker/docker-credential-helpers/releases/download/v0.8.0/docker-credential-pass-v0.8.0.linux-amd64 \
  -o /usr/local/bin/docker-credential-pass

# Make it executable
chmod +x /usr/local/bin/docker-credential-pass

Then update your config.json to point at it:

{
  "credsStore": "pass"
}

You'll also need pass itself installed and initialized. That's a bit of a rabbit hole — pass uses GPG keys under the hood — but if you're running a server or a shared environment, it's worth setting up properly. The Docker docs have decent instructions for that part.

On macOS, if you're not using Docker Desktop, you can install the keychain helper via Homebrew:

brew install docker-credential-helper

Then set credsStore to osxkeychain in your config.

Fix 3: The WSL2 Specific Version of This Nightmare

Now here's where it gets tricky. If you're on Windows using Docker with WSL2 (Windows Subsystem for Linux), you might be hitting a slightly different version of this error. The WSL environment and the Windows host don't always share PATH the way you'd expect, so even if Docker Desktop is installed on Windows, the credential helper binary isn't visible inside your WSL terminal.

Check what your config looks like inside WSL:

cat ~/.docker/config.json

If it says "credsStore": "desktop" and you're inside a WSL shell, that binary lives on the Windows side and WSL can't find it. The same edit from Fix 1 applies — remove or clear the credsStore value. Alternatively, make sure Docker Desktop's WSL integration is actually enabled. Go into Docker Desktop → Settings → Resources → WSL Integration and toggle on the distro you're using. That sometimes resolves the PATH issue entirely without touching any config files.

(Side note: the Docker Desktop WSL integration has been flaky across a few versions — I've seen it randomly disable itself after updates. Worth checking that setting first before digging into config files.)

Fallback: Nuclear Option When Nothing Else Works

If you've tried all of the above and Docker is still being stubborn, just blow away the config and start fresh:

mv ~/.docker/config.json ~/.docker/config.json.bak
docker login

Backing it up first in case you had other settings in there — custom registries, proxy configs, that kind of thing. But nine times out of ten, a fresh login with an empty config sorts everything out. You can then manually re-add whatever else you need.

Also worth running docker info after you fix it to confirm Docker's seeing the right context and isn't still confused about credentials from a cached state somewhere.

Hope this saves you the 45 minutes I lost staring at that error the first time I hit it. The fix is almost always in that config.json — Docker's error message just isn't great at telling you that directly.