Introduction

The Docker error saying access to the requested resource is not authorized usually appears during docker pull, docker push, or image builds that depend on a private base image. The message is generic, but the root cause is usually one of four things: wrong registry credentials, wrong repository name, missing permissions, or pointing at the wrong registry entirely.

Understand What Docker Is Trying to Reach

Before fixing credentials, verify the exact image reference. Docker image names encode registry, namespace, repository, and tag, and one typo can send the client to a different registry than you intended.

For example:

docker pull my-registry.example.com/team/api:1.4.2

This is different from:

docker pull team/api:1.4.2

The second command defaults to Docker Hub, not your private registry. If the image only exists in the private registry, Docker Hub responds with an authorization or repository error that looks like a login problem even when the real issue is the image path.

Re-Authenticate Explicitly

If the image path is correct, refresh authentication first. Docker caches registry credentials locally, and stale tokens are a common cause of this error.

docker logout my-registry.example.com
docker login my-registry.example.com

For Docker Hub, the login command is simply:

docker login

After logging in again, retry the exact pull or push command. If you use an access token instead of a password, make sure the token still exists and has the required scopes.

Verify Repository Permissions

Authentication and authorization are different. You may be logged in successfully but still lack permission to the repository.

Common examples:

• you can read public images but not private team images
• you can pull from a repository but not push to it
• your CI token can authenticate but is limited to one namespace

This matters especially in GitHub Container Registry, ECR, GitLab Container Registry, and self-hosted registries where repository-level permissions are separate from account login.

A quick sanity check is to try a repository you know you own. If that works but the target repository does not, the problem is likely access policy rather than Docker itself.

Watch for CI and Build Context Issues

This error often appears inside docker build when the Dockerfile uses a private base image.

FROM my-registry.example.com/team/private-base:latest
COPY . /app

In that case, the failure may not be about the final push. The builder cannot even fetch the base image. In CI, make sure the registry login happens before docker build, not only before docker push.

docker login my-registry.example.com -u "$REGISTRY_USER" -p "$REGISTRY_TOKEN"
docker build -t my-registry.example.com/team/app:latest .

If you use BuildKit or a remote builder, confirm the builder environment also has access to the same credentials.

Registry-Specific Cases

Different registries produce similar messages for slightly different causes:

• Docker Hub may return this when the repository name is wrong or private.
• Amazon ECR requires a fresh login token from AWS CLI.
• GitHub Container Registry often requires a token with package read or write scope.
• Self-hosted registries may reject access because of TLS or proxy misconfiguration, which then looks like authorization failure.

For ECR, the login flow is different:

aws ecr get-login-password --region us-east-1 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` ## Common Pitfalls - Pulling from Docker Hub by accident because the registry hostname was omitted. - Logging in successfully but using an account that lacks repository permissions. - Authenticating after `docker build` even though the build needs a private base image. - Using expired CI tokens or personal access tokens with the wrong scopes. - Assuming the problem is Docker itself when the repository name is wrong. ## Summary - This error usually means wrong credentials, wrong image path, or missing repository permissions. - Verify the full image reference before changing authentication. - Refresh registry login explicitly and retry the same command. - Check whether the account or token has pull or push access to that repository. - In CI and builds, authenticate before any step that fetches a private image.