Victor's room

Quick Summary: The error error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH occurs when the Docker CLI attempts to authenticate or query registry credentials using an external helper binary that is missing from your system. This commonly happens after migrating from Docker Desktop to Docker Engine on Linux, syncing configuration files across different operating systems, or uninstalling Docker Desktop while leaving stale settings in ~/.docker/config.json.

Understanding the Root Causes

When executing commands such as docker login, docker pull, docker push, or docker build, the Docker CLI inspects your local configuration to find secure storage providers for registry tokens. The failure triggers due to:

• Stale credsStore Directive: The ~/.docker/config.json file contains "credsStore": "desktop", but Docker Desktop has been uninstalled, never installed (pure Linux server), or its helper binary was removed from /usr/local/bin.
• Cross-Platform Dotfile Sync: Sharing .docker/config.json from macOS or Windows (which rely on Desktop or keychain credential helpers) to a remote Linux VM or CI/CD runner.
• PATH Misconfiguration: Docker Desktop is installed, but its auxiliary binary directory (e.g., /opt/docker-desktop/bin or ~/.docker/bin) is omitted from the shell’s $PATH environment variable.

Step 1: Quick Fix – Remove the Stale credsStore Directive

If you are using standalone Docker Engine on Linux and store authentication tokens natively or in CI/CD, the fastest fix is removing the invalid helper configuration:

# Backup your existing Docker configuration
cp ~/.docker/config.json ~/.docker/config.json.bak

# View the current configuration
cat ~/.docker/config.json

# Edit ~/.docker/config.json using a text editor
nano ~/.docker/config.json

Locate the line defining "credsStore": "desktop" and delete it, or set the file to standard configuration structure:

{
  "auths": {}
}

Alternatively, use sed or jq to remove the key directly in a one-liner:

# Remove the credsStore key using jq
jq 'del(.credsStore)' ~/.docker/config.json > ~/.docker/config.tmp && mv ~/.docker/config.tmp ~/.docker/config.json

Step 2: Configure a Valid Linux Credential Helper (Optional)

If your organization requires encrypted credential storage on Linux instead of storing base64-encoded credentials in plaintext, install and configure a supported credential helper like pass or secretservice:

# Install the native secretservice helper on Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y pass docker-compose-plugin

# Download the official docker-credential-pass binary (or install via package manager)
sudo apt-get install -y golang-docker-credential-helpers

# Update ~/.docker/config.json with the valid helper
nano ~/.docker/config.json

# Set credsStore to 'pass' or 'secretservice':
{
  "credsStore": "secretservice"
}

Step 3: Fix PATH if Docker Desktop is Actually Installed

If you intended to run Docker Desktop on Linux or macOS and received this error, verify that the application binaries are present and added to your shell profile:

# Check if docker-credential-desktop exists in typical locations
which docker-credential-desktop || ls -l /opt/docker-desktop/bin/docker-credential-desktop

# If located in /opt/docker-desktop/bin, export it in your ~/.bashrc or ~/.zshrc
echo 'export PATH="$PATH:/opt/docker-desktop/bin"' >> ~/.bashrc
source ~/.bashrc

# Create a symlink to standard system PATH as an alternative
sudo ln -sf /opt/docker-desktop/bin/docker-credential-desktop /usr/local/bin/docker-credential-desktop

Verification & Testing Steps

Test the Docker CLI to verify that registry operations succeed without credential helper warnings:

# Test pulling a public image without authentication errors
docker pull hello-world

# Test Docker login workflow
docker login

# Verify current authentication status
docker info | grep -i "Registry"

Troubleshooting Summary Comparison

Environment / Scenario	Root Cause	Recommended Solution
Headless Linux / CI Runner	Stale credsStore: desktop in config	Delete credsStore key from ~/.docker/config.json
Linux with Desktop Uninstalled	Binary deleted but configuration remains	Remove helper directive or install secretservice
Docker Desktop on Linux/macOS	Helper binary missing from shell $PATH	Add /opt/docker-desktop/bin to PATH or symlink
Secure Production Server	Need encrypted token storage	Install pass and configure credsStore: pass