Fix Docker "Error Getting Credentials"

You run docker pull, docker push, or docker build, and Docker stops with error getting credentials. The message may name a missing program, such as docker-credential-desktop, or report a problem with your keyring or password store. Docker is trying to read registry credentials through a helper that it cannot use.
This guide explains where Docker keeps its credential settings and how to fix the error by removing a stale setting or repairing the helper you want to use. The Linux examples were tested with Docker 29.1.3 on Ubuntu 26.04.1 LTS.
What the Error Means
After uninstalling Docker Desktop or copying a configuration from another machine, you may see this error:
error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ``The message tells us that Docker tried to run docker-credential-desktop, but the executable was not on the client’s PATH. A credential helper is a separate program that reads and writes registry credentials in a keychain or password store.
Docker selects the helper through two settings in its client configuration:
credsStore- The default helper for registries.credHelpers- Helpers for individual registries. A matching entry takes precedence overcredsStoreand credentials inauths.
The value is the part of the executable name after docker-credential-. For example, "credsStore": "desktop" selects docker-credential-desktop.
An executable file not found message means Docker could not find the helper. An exit status 1 message means the helper ran and failed; read the text after out: for the cause. These are client-side credential settings, so restarting the Docker daemon does not repair them.
Find the Active Docker Configuration
By default, Docker reads ~/.docker/config.json. The DOCKER_CONFIG environment variable changes the directory, and the global docker --config DIRECTORY option overrides both. Check the configuration for the same user and shell that produced the error.
If your command does not use --config, print the configuration path with:
docker_config_dir="${DOCKER_CONFIG:-$HOME/.docker}"
printf '%s\n' "$docker_config_dir/config.json"If you use docker --config /path/to/config, set docker_config_dir to that directory instead. The remaining examples use this variable.
Before editing the file, make a backup:
cp -p "$docker_config_dir/config.json" "$docker_config_dir/config.json.bak-$(date +%Y%m%d-%H%M%S)"Open the file in your text editor:
nano "$docker_config_dir/config.json"Look for credsStore and credHelpers. For example, this configuration uses the Desktop helper by default and for a specific registry:
{
"auths": {},
"credsStore": "desktop",
"credHelpers": {
"registry.example.com": "desktop"
}
}Here, changing only credsStore would leave registry.example.com using the Desktop helper. Check the executable named in your error:
command -v docker-credential-desktopIf the command prints nothing, the executable is missing from this shell’s PATH. Substitute docker-credential-pass, docker-credential-secretservice, or the other helper named in your error.
Remove a Stale Credential Helper
If you no longer use Docker Desktop, remove the stale "credsStore": "desktop" setting. Also remove any credHelpers entry for the failing registry if it points to the same unavailable helper. Keep entries for other registries that still work, along with your other Docker settings.
For the minimal configuration above, removing both Desktop settings leaves:
{
"auths": {}
}Do not replace your entire file with this example. Remove only the affected properties, and make sure the remaining JSON has no trailing commas. If Python 3 is installed, you can check the JSON syntax without printing credentials:
python3 -m json.tool "$docker_config_dir/config.json" > /dev/nullThe command returns without output when the JSON is valid. If it reports an error, correct the indicated line before continuing.
Try the command that failed. For a public image, you can check with:
docker pull hello-worldIf the pull completes, Docker can access the registry without the broken helper. For a private image, log in to its registry again before retrying the pull:
docker login registry.example.comReplace registry.example.com with your registry’s hostname, including its port if needed. For Docker Hub, use docker login without a hostname; current Docker versions use a browser-based device-code flow by default.
Removing credsStore does not always force file-based storage. With no authentication configuration present, Docker can automatically select a native helper. On Linux, its default selection uses pass when available, otherwise secretservice; if the selected helper executable is unavailable, Docker falls back to the configuration file. See Docker’s credential store documentation
for the platform defaults.
If the error changes to mention pass or secretservice, follow the setup below. Renaming credsStore to credStore only makes Docker ignore the property and does not repair the helper.
config.json, the auth value is base64-encoded, not encrypted. Restrict access with chmod 600 "$docker_config_dir/config.json" and keep the file out of Git, for example with a .gitignore rule if your Docker configuration is inside a project. A working credential helper is preferable for stored logins.Setting Up a Working Credential Helper
If you still use Docker Desktop, start it and check its installation before removing its credential settings. The Desktop helper is part of Docker Desktop; installing the Linux helper package below does not provide docker-credential-desktop.
For Docker Engine on Linux, choose a helper that suits your login session. On Ubuntu, Debian, and derivatives, the following package provides both docker-credential-secretservice and docker-credential-pass:
sudo apt update
sudo apt install golang-docker-credential-helpersThe executables must be on the PATH of the user running Docker. Installing them is only the first step; their backing stores must also be ready to use.
Linux Desktop: secretservice
The secretservice helper uses a D-Bus Secret Service, such as GNOME Keyring. Use it from your normal desktop login session, with the keyring unlocked. On a minimal server, installing the helper alone does not create a working desktop keyring.
Check that the helper is available:
command -v docker-credential-secretserviceSet the default store to secretservice, preserving the other settings in your file:
{
"auths": {},
"credsStore": "secretservice"
}If the failing registry has a credHelpers entry, update that entry to secretservice too, or remove it so the registry uses the default store. Then run docker login for the registry again from the desktop terminal.
Linux Server: pass
The pass helper uses a GPG-encrypted password store and does not need a desktop keyring. Install pass alongside the helper package:
sudo apt install passFor an interactive SSH session, tell GPG which terminal to use for passphrase prompts:
export GPG_TTY="$(tty)"If you already use pass, keep your existing store. Otherwise, list your GPG secret keys:
gpg --list-secret-keys --keyid-format LONGIf you do not have a suitable key, create one and follow the prompts:
gpg --full-generate-keyFor a new password store, initialize it with the fingerprint of your chosen key. Replace YOUR_GPG_KEY_FINGERPRINT with the fingerprint shown by GPG:
pass init YOUR_GPG_KEY_FINGERPRINTSet credsStore to pass, again preserving your other settings and checking any registry-specific override:
{
"auths": {},
"credsStore": "pass"
}Run docker login for your registry again. The helper now stores the login in the initialized password store. See the pass setup documentation
for more about choosing a GPG key. Unattended jobs need their own credential and key-unlocking setup; an interactive passphrase prompt will not work in CI.
Troubleshooting
The executable exists, but the error says exit status 1
Read the message after out:. A D-Bus or locked-keyring error points to the session used by secretservice. A password-store initialization or GPG error points to pass. Reinstalling the executable does not initialize or unlock its store.
The error happens only with sudo or in CI
Those commands can run with a different home directory, PATH, and desktop session. sudo docker normally uses root’s configuration rather than yours. Inspect the configuration and helper for the account that actually runs the command. A helper found in your interactive shell may be unavailable to root or the CI runner.
Login succeeds, but a build or pull still uses the old helper
Check for a --config option or a different DOCKER_CONFIG value in the script running the command. Also check credHelpers for the image’s registry. A login to Docker Hub does not test the helper configured for a separate private registry. Docker documents the configuration precedence
in its CLI reference.
Docker can read credentials, but the registry returns unauthorized
The helper error is resolved. Check the account, token expiry, registry hostname, and permission to pull or push that repository. Log in to the same registry used in the image name.
Conclusion
Keep credential settings specific to the machine and account using them, especially when moving from Docker Desktop to a server. If the error interrupted a build, return to the Dockerfile guide after the base image pulls successfully.
Tags
Linuxize Weekly Newsletter
A quick weekly roundup of new tutorials, news, and tips.
About the authors

Dejan Panovski
Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 1000+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.
View author page