Introduction
A frequent Amazon ECR login failure looks like this: Error saving credentials: error storing credentials - err: exit status 1, out: not implemented. The AWS authentication step often succeeds, but Docker fails while trying to store the token in its configured credential helper. This is common in WSL, minimal Linux containers, CI runners, and headless systems where desktop keychain integrations are missing.
The key insight is that login and credential storage are separate operations. aws ecr get-login-password can return a valid token, yet Docker still errors when the credential backend in ~/.docker/config.json is unavailable. Fixing the credential store configuration usually resolves the issue immediately.
Core Sections
1. Validate the standard ECR login flow first
Use the canonical command sequence and confirm AWS identity is correct:
aws sts get-caller-identity
aws ecr get-login-password --region us-east-1 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` If this still fails with “not implemented,” the problem is almost certainly Docker credential helper configuration. ### 2. Inspect Docker credential settings Open `~/.docker/config.json` and look for `credsStore` or `credHelpers`. ```json { "auths": {}, "credsStore": "desktop" } ``` In many non-desktop environments, `desktop` (or another helper) is unavailable, causing the storage error. You can temporarily remove `credsStore` to verify: ```bash cp ~/.docker/config.json ~/.docker/config.json.bak jq 'del(.credsStore)' ~/.docker/config.json > /tmp/docker-config.json mv /tmp/docker-config.json ~/.docker/config.json ``` Then retry login. ### 3. Use an environment-specific Docker config in CI In pipelines, avoid global credential-helper assumptions by isolating Docker config: ```bash export DOCKER_CONFIG="$(mktemp -d)" cat > "$DOCKER_CONFIG/config.json" <<'JSON' { "auths": {} } JSON aws ecr get-login-password --region us-east-1 \ | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` This approach prevents runner-specific helper mismatches and makes builds reproducible. ### 4. Install and configure a supported helper when persistence is needed If you need persistent secure storage, install a supported helper for your platform (`pass`, `secretservice`, `osxkeychain`, `wincred`) and set it explicitly. ```json { "credsStore": "pass", "auths": {} } ``` Then test helper functionality independently before retrying ECR login. ### 5. Remember token lifetime and region/account scope ECR auth tokens expire (typically 12 hours). Also, registry URLs are region- and account-specific. A valid token for one registry does not authorize another. ## Common Pitfalls * Assuming AWS IAM permission is wrong when the real failure is Docker credential backend setup. * Leaving `credsStore` set to `desktop` in non-desktop environments like WSL or CI. * Reusing one `DOCKER_CONFIG` across parallel jobs, creating nondeterministic credential races. * Logging into the wrong account or region endpoint and treating it as a credential-helper problem. * Forgetting token expiry and expecting one login to work indefinitely. ## Summary “Error saving credentials... not implemented” during ECR login usually means Docker cannot use the configured credential store, not that AWS authentication failed. Confirm the standard login command, inspect `config.json`, and either remove unsupported helpers for ephemeral environments or install the correct helper for persistent secure storage. In CI, isolate `DOCKER_CONFIG` per job for deterministic behavior. Once credential storage is aligned with the runtime platform, ECR login becomes reliable and repeatable. A practical way to keep this issue from returning is to turn the fix into a lightweight runbook. Capture the exact environment assumptions (tool versions, runtime flags, cluster or platform settings, and required dependencies), then store a short verification command sequence that any teammate can run from a clean setup. This makes troubleshooting deterministic instead of person-dependent and reduces rework during on-call incidents. It also helps to add one automated guardrail in CI or pre-deploy checks that validates the critical assumption described above. That guardrail might be a linter rule, a smoke test, a schema check, a policy validation step, or a minimal integration test. When the same class of failure is caught before release, teams spend less time on emergency debugging and more time on controlled improvements.
