🚨 Docker Error Guide: 'error getting credentials - err: exit status 1' — Fix Credential Helpers

Overview

Docker fails before it even contacts a registry when it cannot retrieve stored credentials from its configured credential helper:

error getting credentials - err: exit status 1, out: ''

This is a client-side failure. The Docker CLI reads ~/.docker/config.json, sees a credsStore or credHelpers entry, and tries to run an external docker-credential-<name> binary to fetch the login. When that helper is missing, not on PATH, or errors out (often because there is no desktop keychain/secret service available), you get this message — with an empty out: '' because the helper produced nothing.

Symptoms

• Every docker pull, push, or login fails instantly with error getting credentials - err: exit status 1, out: ''.
• It started after installing Docker Desktop, pass, or a keychain integration.
• It happens in CI or over SSH where no graphical keyring/secret service is running.
• docker login itself fails the same way, so you cannot even re-authenticate.

Common Root Causes

• Missing credential helper binary — config.json names a credsStore (e.g. desktop, secretservice, pass) whose docker-credential-* binary is not installed or not on PATH.
• Helper backend unavailable — secretservice with no D-Bus/keyring running (headless server), or pass with no initialized GPG store.
• Corrupt config.json — malformed JSON or stale entries the helper chokes on.
• PATH not set for non-interactive shells — CI/cron runs where the helper exists but is not on the reduced PATH.
• Wrong credsStore name after copying a config between machines (e.g. desktop on a server without Docker Desktop).

Diagnostic Workflow

Read the config to find which helper Docker is trying to invoke:

cat ~/.docker/config.json
# look for "credsStore": "..."  and/or "credHelpers": { ... }

Check whether the corresponding binary actually exists on PATH:

credsStore=$(grep -o '"credsStore" *: *"[^"]*"' ~/.docker/config.json | cut -d'"' -f4)
echo "helper: docker-credential-$credsStore"
which docker-credential-$credsStore

If which finds nothing, that is the problem. Test the helper directly to see the real error it emits:

echo "https://registry.example.com" | docker-credential-$credsStore get

Confirm the config is valid JSON:

python3 -m json.tool ~/.docker/config.json >/dev/null && echo "valid JSON"

Example Root Cause Analysis

After a laptop’s ~/.docker/config.json was copied to a headless build server, every Docker command there failed with error getting credentials - err: exit status 1, out: ''.

The config named the Docker Desktop helper, which does not exist on a plain Linux server:

grep credsStore ~/.docker/config.json
# "credsStore": "desktop"
which docker-credential-desktop
# (nothing)

The server had no docker-credential-desktop binary, so the CLI’s attempt to fetch credentials failed immediately. Two valid fixes exist. The simplest on a server is to remove the credsStore line so Docker stores credentials (base64) directly in config.json:

# edit ~/.docker/config.json and delete the "credsStore": "desktop" line, then:
docker login registry.example.com

Alternatively, install and configure a helper that fits the environment (for example docker-credential-pass with an initialized GPG/pass store) and set credsStore to pass. After removing the invalid desktop helper and logging in again, all registry operations worked.

Prevention Best Practices

• Do not copy ~/.docker/config.json between machines with different helpers; the credsStore value is host-specific.
• On headless servers and CI, prefer no credsStore (plain config storage) or a helper that works without a GUI keyring, such as pass.
• Ensure docker-credential-* binaries are installed and on the PATH used by non-interactive shells and cron.
• Validate config.json is well-formed JSON after manual edits.
• Keep credential handling consistent across environments using the Docker stack guide, and lint image builds with the Dockerfile validator.

Quick Command Reference

cat ~/.docker/config.json                                     # find credsStore / credHelpers
which docker-credential-desktop docker-credential-pass        # is the helper installed?
echo "https://registry.example.com" | docker-credential-pass get   # test helper directly
python3 -m json.tool ~/.docker/config.json >/dev/null && echo OK   # valid JSON?
# Fix on a server: remove the "credsStore" line, then:
docker login registry.example.com

Conclusion

error getting credentials - err: exit status 1, out: '' is a broken credential-helper problem, not a registry problem. Docker is trying to run a docker-credential-* binary that is missing, not on PATH, or backed by an unavailable keyring. Read config.json to find the named helper, test it directly, and either install/configure the right one or remove the credsStore entry so Docker stores credentials in the config file. Then docker login again and your registry commands will flow.