Fix Docker ECR pull 403 Forbidden from expired authentication

Problem

Pulling or building a Docker image that references an AWS ECR registry fails with a 403 Forbidden error:

failed to resolve source metadata for 724013829182.dkr.ecr.us-west-2.amazonaws.com/node:18-slim:
unexpected status from HEAD request at
https://724013829182.dkr.ecr.us-west-2.amazonaws.com/v2/node/manifests/18-slim:
403 Forbidden

This typically happens when an ECR authentication token has expired. The token was cached in ~/.docker/config.json from a previous docker login session, but ECR tokens are only valid for 12 hours.

Solution

Re-authenticate with ECR before pulling or building:

aws ecr get-login-password --region us-west-2 \
  | docker login --username AWS --password-stdin \
    724013829182.dkr.ecr.us-west-2.amazonaws.com

Replace the account ID and region with your own values. After successful login, retry the pull:

docker pull 724013829182.dkr.ecr.us-west-2.amazonaws.com/node:18-slim

For CI/CD pipelines, add an authentication step before any Docker build or pull:

# GitHub Actions example
- name: Login to Amazon ECR
  uses: aws-actions/amazon-ecr-login@v2

- name: Build and push
  run: docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .

For long-running environments, configure the ECR credential helper to auto-refresh tokens:

// ~/.docker/config.json
{
  "credHelpers": {
    "724013829182.dkr.ecr.us-west-2.amazonaws.com": "ecr-login"
  }
}

This requires amazon-ecr-credential-helper to be installed. The helper fetches a fresh token on each Docker operation, eliminating manual re-login.

Why It Works

AWS ECR issues temporary authentication tokens that expire after 12 hours. Docker stores the token in ~/.docker/config.json as a base64-encoded credential and reuses it for subsequent requests. Once the token expires, ECR returns 403 Forbidden for all registry operations. Running aws ecr get-login-password generates a fresh token from your AWS credentials, and piping it to docker login updates the cached credential. The ECR credential helper avoids this entirely by fetching a new token on demand for each Docker operation.

Context

• AWS ECR (Elastic Container Registry) with any Docker-compatible client
• If using AWS SSO, run aws sso login first to refresh your AWS session before running ecr get-login-password
• The 12-hour expiration also affects docker build when the Dockerfile uses FROM with an ECR image reference
• For multi-region setups, you must authenticate to each region's ECR endpoint separately
• The amazon-ecr-credential-helper can be installed via apt, brew, or downloaded from the AWS GitHub releases
• In Kubernetes environments, use ECR image pull secrets or IRSA (IAM Roles for Service Accounts) with the credential helper for automatic token rotation