Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker login fails when storing credentials

Errorerror storing credentials

Short answer

docker login hands your password to a credential helper named in ~/.docker/config.json. If that helper is not installed, not on PATH, not initialised, or not the one the setting names, the store step fails. Check credsStore and credHelpers, install or correct the helper, or remove the setting.

  • Applies to Docker Engine 28, Docker CLI 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the client config. The credsStore or credHelpers value is the name of the program Docker runs, with docker-credential- put in front.

    cat ~/.docker/config.json
    which docker-credential-desktop docker-credential-pass docker-credential-secretservice
  2. 2Match what you see, then jump to its fix

    1. 1executable file not found in $PATHThe named credential helper is not installed or not on PATHFix
    2. 2error storing credentials with credsStore set to passThe pass helper is installed but not initialisedFix

What does the error look like?

  • error storing credentials
  • executable file not found in $PATH

Cause 1 of 2

The named credential helper is not installed or not on PATH

1Check

Take the value of credsStore (for example desktop, osxkeychain or pass), add the docker-credential- prefix, and see whether that program exists. A config copied from a machine with Docker Desktop often names a helper the new machine lacks.

grep -E 'credsStore|credHelpers' ~/.docker/config.json
command -v docker-credential-desktop || echo "helper missing"

2Fix

Install the helper from the docker-credential-helpers releases and put the binary on PATH, or change credsStore to a helper that is installed. Without any helper, Docker falls back to base64 text in config.json, which is less secure.

# edit ~/.docker/config.json so the name matches an installed helper
{ "credsStore": "secretservice" }

3Verify

Log in again.

docker login

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

The pass helper is installed but not initialised

1Check

The pass helper needs a gpg2 key ID and that key must exist in the gpg2 keyring. A fresh server has neither, so storing fails even though the program is found.

gpg2 --list-keys
pass ls

2Fix

Create or import a gpg2 key and initialise pass with its ID, then log in again. If you do not want a key store on this machine, remove credsStore from config.json and log out first so no old entry is left.

# initialise pass with the key ID shown by gpg2 --list-keys,
# or remove credsStore from ~/.docker/config.json
gpg2 --list-keys

3Verify

docker login stores the credentials without an error.

docker login

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Do not copy ~/.docker/config.json between machines; let each machine create its own.
  • On a headless server, use a helper that works without a desktop session (pass with a gpg key) and keep that key backed up.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.