Fix docker login 'error saving credentials: error storing credentials - err: exit status 1' (AWS ECR on macOS, Windows, Linux and WSL)

This is a troubleshooting blog post on how to fix the following error when running aws ecr get-login-password --region <region> | docker login ... to log in to AWS Elastic Container Registry -

1Error saving credentials: error storing credentials - err: exit status 1, out: `Post http://ipc/registry/credstore-updated: dial unix backend.sock: connect: connection refused`

Here is the screenshot of the error -

The important thing to understand, and the reason this error is so confusing, is that the login itself worked. ECR accepted the token. What failed is the step right after - Docker trying to save that token on your machine through a credential helper. Depending on your operating system the out: part of the message is different, and that part tells you which fix you need -

Table of Content

1. Root cause - how docker login stores credentials
2. Fix 1 - Remove the .docker/config.json file
3. Fix 2 - Allow docker-credential-osxkeychain in Keychain Access (macOS)
4. Fix 3 - "The specified item already exists in the keychain (-25299)" (macOS)
5. Fix 4 - "The stub received bad data" (Windows wincred)
6. Fix 5 - "docker-credential-xxx: executable file not found in $PATH" (any OS, WSL, CI)
7. Fix 6 - pass / secretservice on Linux and headless servers
8. Fix 7 - Install the Amazon ECR Docker Credential Helper (the permanent fix)
9. Related ECR login errors
10. Conclusion

(NOTE - If you are here for the whole push workflow and not just this error, here is the detailed guide on How to push a docker image to AWS ECR)

Root cause - how docker login stores credentials

When you run docker login, Docker does two things. First it authenticates against the registry with the username and password you gave it (for ECR the username is always AWS and the password is the 12-hour token from aws ecr get-login-password). Second, it stores the credentials so that the next docker pull or docker push does not ask again.

Where it stores them is decided by ~/.docker/config.json -

• If the file has no credsStore, Docker writes the credentials, base64-encoded, into the auths section of the file itself. Ugly, but it always works.
• If the file has "credsStore": "osxkeychain", "desktop", "wincred", "pass" or "secretservice", Docker calls an external program named docker-credential-<that> and asks it to store the token in the OS keychain (macOS Keychain, Windows Credential Manager, GNOME Keyring, pass).

Docker Desktop sets credsStore to desktop (which forwards to the OS keychain) by default. Every variant of the error is that helper program failing - it is missing, it is not allowed to touch the keychain, the keychain already has an entry, or (on Windows) the ECR token is simply too long for Credential Manager. The Docker documentation on credential stores explains the mechanism.

Knowing this, the fixes are all one of three things - get out of the helper's way (remove credsStore), fix the helper, or replace it with a helper built for ECR.

1. Remove the .docker/config.json file

The quickest fix on any operating system. When the file is gone, Docker recreates it on the next login without a credsStore, so credentials go into the plain file and no helper is involved.

1. Locate the file - It lives in your home directory -

1# macOS / Linux / WSL
2ls -la ~/.docker/config.json
3
4# Windows (PowerShell)
5Get-Content $env:USERPROFILE\.docker\config.json

Take a look at the content first. If you see a credsStore line, that is the helper which is failing -

1{
2  "auths": {},
3  "credsStore": "desktop"
4}

2. Back it up and remove it - (or just delete the credsStore line and keep the file)

1mv ~/.docker/config.json ~/.docker/config.json.bak

3. Re-run the ECR login -

1# AWS ECR get-login-password command after removing the .docker/config.json file
2
3aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin 242396018804.dkr.ecr.eu-central-1.amazonaws.com

Here is the screenshot of the successful login -

You will now see WARNING! Your credentials are stored unencrypted in '/Users/you/.docker/config.json'. That is the trade-off of this fix. For a laptop it is acceptable to many people, because the ECR token expires after 12 hours anyway, but if you also log in to Docker Hub with a real password you should prefer Fix 7.

Docker Desktop note - Docker Desktop may put the credsStore line back when it restarts. If that happens, go to Docker Desktop settings and disable the credential store option, or use the ECR credential helper in Fix 7.

2. Allow docker-credential-osxkeychain in Keychain Access (macOS)

On macOS the helper writes to the login Keychain, and the first time it does, macOS shows a pop-up asking for permission. If that pop-up never appeared (it is easy to miss behind the terminal), or you clicked Deny, every login fails with exit status 1 and sometimes User interaction is not allowed.

1. Open the Keychain Access application - Spotlight (command + spacebar), type Keychain Access.

2. Find the Docker entries - Search for docker or for your registry host (242396018804.dkr.ecr...). Open the entry, go to the Access Control tab, and allow docker-credential-osxkeychain (or docker-credential-desktop) to access the item, or tick "Allow all applications to access this item" for that entry.

3. Unlock the keychain and retry - If you are logging in over SSH to the Mac or from a CI agent, the keychain is locked and the helper cannot prompt. Unlock it first -

1security unlock-keychain ~/Library/Keychains/login.keychain-db

Then re-run the aws ecr get-login-password | docker login command.

3. "The specified item already exists in the keychain (-25299)" (macOS)

1Error saving credentials: error storing credentials - err: exit status 1, out: `The specified item already exists in the keychain. (-25299)`

The keychain already holds an entry for this registry (from a previous login, often with an expired token) and the helper fails to overwrite it. Delete the stale entry and log in again -

1# 1. log out, which asks the helper to delete the entry
2docker logout 242396018804.dkr.ecr.eu-central-1.amazonaws.com
3
4# 2. if that still fails, delete it directly from the keychain
5security delete-internet-password -s 242396018804.dkr.ecr.eu-central-1.amazonaws.com
6
7# 3. log in again
8aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin 242396018804.dkr.ecr.eu-central-1.amazonaws.com

You can also do step 2 in the Keychain Access app - search for the registry hostname and delete the item. If the error keeps coming back every 12 hours, you have two tools writing the same keychain item (for example Docker Desktop plus a manually configured helper). Pick one, ideally the ECR helper from Fix 7.

4. "The stub received bad data" (Windows wincred)

1Error saving credentials: error storing credentials - err: exit status 1, out: `The stub received bad data.`

This is the Windows version and it has a very specific cause. The wincred helper stores the token in Windows Credential Manager, and Credential Manager has a size limit on the secret. The ECR token is about 1,900 characters, which is over the limit on older Docker Desktop versions. Three ways out, pick one -

Option A - stop using wincred. Open %USERPROFILE%\.docker\config.json and delete the "credsStore": "wincred" (or "desktop") line, so Docker stores the token in the file. Re-run the login.

1{
2  "auths": {}
3}

Option B - update Docker Desktop. Newer versions of Docker Desktop and the credential helpers raised the limit. If you are more than a year behind, updating alone can fix it.

Option C - use the ECR credential helper (Fix 7). It never stores the token at all, it fetches a fresh one from your AWS credentials on every pull and push, so Credential Manager is never involved.

For PowerShell users, the full login command on Windows is -

1(Get-ECRLoginCommand).Password | docker login --username AWS --password-stdin 242396018804.dkr.ecr.eu-central-1.amazonaws.com

or with the AWS CLI -

1aws ecr get-login-password --region eu-central-1 | docker login --username AWS --password-stdin 242396018804.dkr.ecr.eu-central-1.amazonaws.com

5. "docker-credential-xxx: executable file not found in $PATH" (any OS, WSL, CI)

1error getting credentials - err: exec: "docker-credential-osxkeychain": executable file not found in $PATH, out: ``
2error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: ``

Here config.json names a helper that is not installed, or not on the PATH of the shell you are in. The classic case is WSL2 - the config was created by Docker Desktop on the Windows side with "credsStore": "desktop.exe", and inside the Linux distribution that program is not reachable, or the opposite - a config copied from a Mac onto a Linux box.

Check which helper is named and whether it exists -

1grep credsStore ~/.docker/config.json
2which docker-credential-desktop docker-credential-osxkeychain docker-credential-pass 2>/dev/null

Then either install that helper (they are released on the docker-credential-helpers GitHub page), or remove the credsStore line, or point it at the ECR helper. In WSL2 with Docker Desktop integration the correct value is "credsStore": "desktop.exe" and Docker Desktop adds /mnt/c/Program Files/Docker/Docker/resources/bin to the WSL PATH - if that integration is off for your distribution, turn it on in Docker Desktop (Settings, Resources, WSL integration) or drop the line.

In CI pipelines (GitHub Actions, GitLab CI, Jenkins agents) there is no keychain at all, so a credsStore is always wrong there. Make sure the runner's ~/.docker/config.json does not have one, or use the official aws-actions/amazon-ecr-login action, which handles the login and the token for you.

6. pass / secretservice on Linux and headless servers

On Linux the two helpers are pass (GPG-encrypted store) and secretservice (GNOME Keyring over D-Bus). Both fail on a server with no desktop session -

1Error saving credentials: error storing credentials - err: exit status 1, out: `pass store is uninitialized`
2Error saving credentials: error storing credentials - err: exit status 1, out: `The name org.freedesktop.secrets was not provided by any .service files`

For pass - initialise it with a GPG key once -

1gpg --generate-key                 # follow the prompts, note the key id
2pass init "<your-gpg-key-id>"

For secretservice - you need a running keyring daemon, which usually means a logged-in desktop session. On a headless server or in Docker-in-Docker, do not use it.

On any headless box my recommendation is the same - remove credsStore and either accept the plain file (the ECR token expires in 12 hours anyway) or install the ECR credential helper below.

7. Install the Amazon ECR Docker Credential Helper (the permanent fix)

If you push to ECR regularly, the real fix is to stop storing ECR tokens at all. The Amazon ECR Docker Credential Helper from AWS Labs is a docker-credential-ecr-login program which Docker calls on every pull and push. It uses your normal AWS credentials (profile, environment variables, an instance role) to fetch a fresh token each time. No more get-login-password, no more 12-hour expiry, no keychain.

7.1 Installation

macOS

1brew install docker-credential-helper-ecr

Debian / Ubuntu

1sudo apt update
2sudo apt install amazon-ecr-credential-helper

Amazon Linux 2023

1sudo dnf install -y amazon-ecr-credential-helper

Amazon Linux 2

1sudo amazon-linux-extras enable docker
2sudo yum install amazon-ecr-credential-helper

Arch Linux

1git clone https://aur.archlinux.org/amazon-ecr-credential-helper.git
2cd amazon-ecr-credential-helper
3makepkg -si

Windows and anything else - download the docker-credential-ecr-login binary for your platform from the releases page on GitHub and put it in a directory on your PATH.

Verify it is reachable -

1docker-credential-ecr-login version

7.2 Put docker-credential-ecr-login on the PATH

Package managers do this for you. If you downloaded the binary by hand, move it to a directory that is already on the PATH -

1sudo mv ./docker-credential-ecr-login /usr/local/bin/docker-credential-ecr-login
2sudo chmod +x /usr/local/bin/docker-credential-ecr-login

or append its directory to your shell profile -

1# ~/.bashrc or ~/.zshrc
2export PATH="$HOME/bin:$PATH"

7.3 Update ~/.docker/config.json

Tell Docker to use the helper only for your ECR registries, with credHelpers. This is better than credsStore, because Docker Hub and other registries keep working the way they did -

1{
2  "credHelpers": {
3    "public.ecr.aws": "ecr-login",
4    "242396018804.dkr.ecr.eu-central-1.amazonaws.com": "ecr-login"
5  }
6}

Replace the account ID and region with yours. If you want the helper for every registry instead, use "credsStore": "ecr-login" - but then Docker Hub logins will fail, so I do not recommend it.

7.4 Make sure the AWS credentials work

The helper uses the standard AWS credential chain - ~/.aws/credentials, AWS_PROFILE, environment variables, or an IAM role on an EC2 instance or in a container. Check that they resolve and that they have ecr:GetAuthorizationToken plus the pull and push permissions -

1aws sts get-caller-identity
2aws ecr get-authorization-token --region eu-central-1 --query 'authorizationData[0].expiresAt'

To use a specific profile with the helper, set AWS_PROFILE=myprofile in the shell before running Docker. Avoid long-lived access keys where you can - I have written about the options in how to handle AWS credentials in Terraform, and the same advice applies here.

After this, docker pull and docker push to ECR just work, with no docker login at all -

1docker push 242396018804.dkr.ecr.eu-central-1.amazonaws.com/jhooq-app:1.0

Related ECR login errors

1. no basic auth credentials on push - You are not logged in to this registry. The login is per account and per region - 123456789012.dkr.ecr.eu-central-1.amazonaws.com and ...us-east-1... are two different registries. Log in to the one in the image name, or use the credential helper.

2. denied: Your authorization token has expired. Reauthenticate and try again. - The 12-hour token ran out. Run the get-login-password | docker login command again, or switch to the credential helper so it never expires.

3. denied: requested access to the resource is denied - Logged in, but the IAM user or role has no push or pull permission on that repository, or the repository does not exist (ECR does not create it on push). I have a dedicated post on requested access to the resource is denied.

4. Unable to locate credentials from the AWS CLI - aws configure was never run, or the wrong profile is active. Fix the AWS CLI first, then Docker.

5. docker: invalid reference format on push - The image name is wrong, usually a missing tag or an uppercase letter in the repository name. Causes and fixes here.

Conclusion

"Error saving credentials: error storing credentials - err: exit status 1" means ECR said yes and your local credential helper said no. Read the out: part of the message to find the helper and the OS-specific cause, then -

1. For a quick unblock, remove credsStore from ~/.docker/config.json (or the whole file) and log in again.
2. On macOS, allow the helper in Keychain Access or delete the stale keychain item.
3. On Windows, drop wincred or update Docker Desktop.
4. For a permanent fix, install the Amazon ECR credential helper and configure credHelpers for your ECR registries - no more tokens to store or renew.

The AWS side of all this is documented in the Amazon ECR private registry authentication guide, and the complete push workflow in my post on pushing a docker image to AWS ECR.