How to fix error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH in Docker

DockerINTERMEDIATEMEDIUM

The 'docker-credential-desktop executable file not found' error occurs when Docker cannot locate the credential helper binary specified in your configuration. This commonly happens after uninstalling Docker Desktop, switching between Docker installations, or when the credential helper path is misconfigured.

What this error means

This error indicates that Docker is trying to use a credential helper called `docker-credential-desktop` to retrieve stored login credentials, but the helper executable cannot be found in your system's PATH. Docker uses credential helpers to securely store and retrieve authentication credentials for container registries like Docker Hub. When you run `docker login`, Docker saves your credentials using the configured helper. When you later run commands like `docker pull` or `docker push`, Docker calls the credential helper to retrieve those stored credentials. The `docker-credential-desktop` helper is specifically provided by Docker Desktop. When you see this error, it typically means: 1. **Docker Desktop was uninstalled** but the configuration file still references the `desktop` credential store 2. **You're using Docker Engine** (installed via apt/yum) but your config still has Docker Desktop settings 3. **Docker Desktop is not running** - the helper is only available when Docker Desktop is active 4. **WSL2/Linux environment** where the Windows Docker Desktop credential helper isn't accessible 5. **The PATH environment variable** doesn't include the Docker Desktop binaries directory

How to fix "error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH"

1Check your Docker configuration file

First, examine your Docker configuration to see which credential store is configured.

bash

# View the Docker config file
cat ~/.docker/config.json

Look for the credsStore entry. If you see something like this:

json

{
  "credsStore": "desktop"
}

This means Docker is trying to use the Docker Desktop credential helper. If Docker Desktop isn't installed or isn't running, this will cause the error.

On Windows, the config file is at C:\Users\<username>\.docker\config.json and might show:

json

{
  "credsStore": "desktop.exe"
}

2Remove or comment out the credsStore entry

The quickest fix is to remove the credsStore line from your config file. This tells Docker to store credentials directly in the config file (base64 encoded).

bash

# Backup your config first
cp ~/.docker/config.json ~/.docker/config.json.backup

# Edit the config file
nano ~/.docker/config.json

Option A: Remove the credsStore line entirely
Change this:

json

{
  "auths": {},
  "credsStore": "desktop"
}

To this:

json

{
  "auths": {}
}

Option B: Comment it out by renaming the key

json

{
  "auths": {},
  "_credsStore": "desktop"
}

Save the file and try your Docker command again:

bash

docker pull hello-world

3Change credsStore to credStore (Linux/Mac)

On some systems, the issue is a typo or version mismatch between credsStore and credStore. Docker Desktop uses credsStore while standalone Docker Engine often uses credStore.

bash

# Edit the config
nano ~/.docker/config.json

Change:

json

{
  "credsStore": "desktop"
}

To:

json

{
  "credStore": "secretservice"
}

Or simply remove both and let Docker store credentials in plaintext:

json

{
  "auths": {}
}

Note: secretservice is the credential store for Linux desktop environments using D-Bus Secret Service (like GNOME Keyring).

4Start Docker Desktop (if installed)

If you have Docker Desktop installed and want to use it, simply ensure it's running.

On macOS:
- Open Docker Desktop from Applications
- Or run: open -a Docker
- Wait for the whale icon in the menu bar to stop animating

On Windows:
- Start Docker Desktop from the Start menu
- Wait for the whale icon in the system tray to indicate Docker is running

On Linux:

bash

# Start Docker Desktop
systemctl --user start docker-desktop

Once Docker Desktop is running, the docker-credential-desktop binary will be available and the error should resolve.

5Fix WSL2 credential helper access

In WSL2, you may need to create a symbolic link to the Windows Docker Desktop credential helper.

bash

# Create a symlink to the Windows executable
sudo ln -s "/mnt/c/Program Files/Docker/Docker/resources/bin/docker-credential-desktop.exe" /usr/local/bin/docker-credential-desktop.exe

Then update your config to use the .exe extension:

json

{
  "credsStore": "desktop.exe"
}

Alternative: Check WSL integration settings in Docker Desktop
1. Open Docker Desktop on Windows
2. Go to Settings > Resources > WSL Integration
3. Enable integration with your WSL2 distro
4. Restart Docker Desktop and your WSL2 terminal

6Install a standalone credential helper

If you're not using Docker Desktop, you can install a standalone credential helper.

On Linux (using secretservice for desktop environments):

bash

# Download the latest release
VERSION=$(curl -s https://api.github.com/repos/docker/docker-credential-helpers/releases/latest | grep tag_name | cut -d '"' -f 4)
wget "https://github.com/docker/docker-credential-helpers/releases/download/${VERSION}/docker-credential-secretservice-${VERSION}.linux-amd64"

# Make it executable and install
chmod +x docker-credential-secretservice-*
sudo mv docker-credential-secretservice-* /usr/local/bin/docker-credential-secretservice

# Update config.json
cat > ~/.docker/config.json << 'EOF'
{
  "credsStore": "secretservice"
}
EOF

On Linux (using pass for headless/server):

bash

# Install pass first
sudo apt install pass

# Download docker-credential-pass
VERSION=$(curl -s https://api.github.com/repos/docker/docker-credential-helpers/releases/latest | grep tag_name | cut -d '"' -f 4)
wget "https://github.com/docker/docker-credential-helpers/releases/download/${VERSION}/docker-credential-pass-${VERSION}.linux-amd64"

chmod +x docker-credential-pass-*
sudo mv docker-credential-pass-* /usr/local/bin/docker-credential-pass

# Initialize pass with your GPG key
gpg --generate-key  # If you don't have one
pass init "[email protected]"

# Update config.json
cat > ~/.docker/config.json << 'EOF'
{
  "credsStore": "pass"
}
EOF

On macOS (without Docker Desktop):

bash

brew install docker-credential-helper

# Update config.json
cat > ~/.docker/config.json << 'EOF'
{
  "credsStore": "osxkeychain"
}
EOF

7Clear stored credentials and re-login

After fixing the configuration, clear any cached authentication and log in again.

bash

# Remove any existing auth entries
# Edit ~/.docker/config.json and clear the "auths" section:
{
  "auths": {}
}

# Log in to Docker Hub (or your registry)
docker login

# Test that it works
docker pull hello-world

If you need to log in to a private registry:

bash

docker login your-registry.example.com

For CI/CD environments, use stdin to avoid storing credentials:

bash

echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin

Advanced notes

### Understanding Docker Credential Helpers

Docker credential helpers are external programs that follow a specific protocol to store and retrieve credentials. The helper name in credsStore is a suffix - Docker looks for docker-credential-<name> in your PATH.

| credsStore Value | Helper Binary | Storage Backend |
|-----------------|---------------|-----------------|
| desktop | docker-credential-desktop | Docker Desktop's built-in store |
| osxkeychain | docker-credential-osxkeychain | macOS Keychain |
| wincred | docker-credential-wincred | Windows Credential Manager |
| secretservice | docker-credential-secretservice | Linux D-Bus Secret Service |
| pass | docker-credential-pass | GPG-encrypted pass store |

### Debugging Credential Helper Issues

Test if a credential helper is accessible:

bash

# Check if the binary exists in PATH
which docker-credential-desktop

# Test the helper directly
echo "https://index.docker.io/v1/" | docker-credential-desktop get

# List what credentials are stored
docker-credential-desktop list

### credsStore vs credHelpers

You can use credHelpers to configure different helpers per registry:

json

{
  "auths": {},
  "credHelpers": {
    "registry.example.com": "secretservice",
    "gcr.io": "gcr",
    "public.ecr.aws": "ecr-login"
  }
}

This is useful when:
- Different registries require different authentication methods
- You want to use AWS ECR or Google GCR native helpers
- Some registries should use secure storage while others use plaintext

### Docker Desktop Configuration Files

Docker Desktop maintains its own settings separate from the CLI config:
- macOS/Windows: ~/.docker/desktop/settings.json
- Contains credentialHelper setting that may override config.json

### Security Considerations

When you remove credsStore, Docker stores credentials as base64 in config.json:

json

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "dXNlcm5hbWU6cGFzc3dvcmQ="
    }
  }
}

This is not encrypted - anyone with read access to the file can decode it:

bash

echo "dXNlcm5hbWU6cGFzc3dvcmQ=" | base64 -d
# Output: username:password

For production systems, use a proper credential helper or token-based authentication.

### WSL2 Specific Behavior

In WSL2 with Docker Desktop:
1. Docker Desktop creates /mnt/wsl/docker-desktop/cli-tools/usr/bin/docker-credential-desktop.exe
2. The WSL integration should add this to PATH automatically
3. If not working, check that WSL integration is enabled in Docker Desktop settings

### Colima Users (macOS Alternative to Docker Desktop)

If using Colima instead of Docker Desktop:

bash

# Remove desktop credential helper reference
# Use osxkeychain instead
cat > ~/.docker/config.json << 'EOF'
{
  "credsStore": "osxkeychain"
}
EOF

How to fix error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH in Docker

What this error means

Typical symptoms

Common causes

How to fix "error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH"

Advanced notes

Related errors

Official resources & further reading