Fix it fast
Most likely: Docker is sending a credential for the registry, but the registry rejects that username/password or token as wrong, expired, or stale.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
unauthorized: incorrect username or passwordCheck the cause
Run focused checks to identify what is failing in this environment.
docker logout <registry>
docker login <registry>
docker manifest inspect <registry>/<namespace>/<repository>:<tag>Apply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# Clear the stale credential, then log in with a fresh token for the correct account.
docker logout <registry>
docker login <registry>
docker pull <registry>/<namespace>/<repository>:<tag>Verify it works
Repeat the relevant checks and confirm the original error is gone.
docker login <registry>
docker pull <registry>/<namespace>/<repository>:<tag>Avoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not keep retrying the same cached credential, clear it first.
- Do not pass passwords directly in command arguments or CI logs.
- Do not assume a token for one registry, organization, or account can authenticate another.
What Access Failed
This is usually a target-and-identity problem, not a syntax problem. The request made it to the server, but the server did not like the credentials, permissions, or repository path attached to it.
Fix credentials and target access
Clear the bad credential first:docker logout <registry>
Log in again with the correct username and a current password or access token.
If you use a credential helper or OS keychain, remove the stale entry there as well before retrying.
If this fails in CI only, rotate the secret and verify the job is using the updated value.
Manual authentication checks
Check whether Docker is pulling credentials from a keychain helper instead of plain auths in ~/.docker/config.json.
Verify the registry username matches the account that owns or can access the repository.
If the secret was rotated recently, confirm the old value is not still cached in CI.
Why It Happens
Usually this comes down to the username, password, or access token is wrong, a credential helper returned stale credentials after the token was rotated, or CI is using the wrong secret or the wrong account for the target registry.
Prove the Failing Environment Can Reach It
Retry the same pull or push and confirm the incorrect-password error is gone, and perform a fresh docker login <registry> and confirm it succeeds without reusing cached credentials.
How registry authentication works
Docker attaches stored credentials for the target registry host when it authenticates. If those credentials are stale or wrong, the registry rejects the login or repository request immediately.
Keep Credentials and Targets Aligned
To prevent this, prefer scoped tokens over long-lived passwords for automation, rotate registry tokens on a schedule and update all consuming jobs together, and avoid sharing one mutable credential across unrelated environments.