Docker Registry Push Failed: Authentication Token Expired on Alpine Linux

Resolve 'authentication token expired' errors when pushing Docker images from Alpine Linux. Learn to re-authenticate, clear credentials, and fix common causes.

When working with Docker on minimal environments like Alpine Linux, encountering an "authentication token expired" error during a docker push operation can halt your CI/CD pipelines or local development workflow. This guide provides a detailed, technical breakdown of the root causes and offers a robust step-by-step resolution path for DevOps engineers and system administrators.

Introduction

You're attempting to push a Docker image to a remote registry (e.g., Docker Hub, AWS ECR, Azure Container Registry, or a private registry) from an Alpine Linux host, but the operation fails with a message indicating that your authentication token has expired. This typically means your current Docker session's credentials for that specific registry are no longer valid, preventing the successful upload of your image layers.

Symptom & Error Signature

The primary symptom is the failure of the docker push command. You will see output similar to the following in your terminal or CI/CD logs:

$ docker push myregistry.com/myusername/myimage:latest
The push refers to repository [myregistry.com/myusername/myimage]
...
denied: requested access to the resource is denied
unauthorized: authentication required
unauthorized: authentication token expired

Or, for specific cloud registries:

$ docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo:latest
The push refers to repository [123456789012.dkr.ecr.us-east-1.amazonaws.com/my-ecr-repo]
...
denied: Your authorization token has expired. Reauthenticate and try again.

Root Cause Analysis

The "authentication token expired" error signifies that the short-lived credential used by Docker to authenticate with the registry is no longer valid. Here's a breakdown of the underlying reasons:

1. Token Lifespan Enforcement: Docker registries, especially cloud-based ones (like AWS ECR, Azure ACR) and many private registry implementations, issue authentication tokens with a limited lifespan for security reasons. These tokens automatically expire after a set period (e.g., 12 hours for AWS ECR, 3600 seconds for generic token services). This minimizes the risk of compromised long-lived credentials.

2. Infrequent Authentication: If you authenticated a long time ago (e.g., several hours or a day) and haven't performed any registry operations since, the token may have expired in the interim. This is common in environments where docker login is performed manually and not frequently.

3. CI/CD Pipeline Inactivity/Restart: In CI/CD contexts, if a build agent or runner is reused or restarts, its Docker authentication state might be lost or become stale, leading to expired tokens. Similarly, long-running pipelines might hit the token expiry during a build.

4. Credential Helper Issues: For registries requiring external credential helpers (e.g., aws-cli for ECR, az cli for ACR), the helper itself might be failing to generate a fresh, valid token, or its own underlying credentials (e.g., IAM roles, service principal tokens) might be expired or revoked.

5. System Clock Skew: Although less common for a direct "token expired" message, significant clock differences between your Alpine host and the registry server can lead to authentication failures. A server might deem a token invalid if its issue/expiry timestamps appear to be in the future or too far in the past relative to the server's clock.

6. ~/.docker/config.json Corruption or Stale Entry: Docker stores authentication tokens and configuration in ~/.docker/config.json. If this file becomes corrupted, or if a specific registry's entry is stale or malformed, it can prevent successful re-authentication or token refreshing.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the "authentication token expired" error on your Alpine Linux system.

1. Re-authenticate with the Docker Registry

The most common and effective solution is simply to re-authenticate with the target Docker registry. This will acquire a new, fresh token.

docker login myregistry.com

Replace myregistry.com with the actual hostname of your Docker registry (e.g., docker.io for Docker Hub, 123456789012.dkr.ecr.us-east-1.amazonaws.com for AWS ECR).

You will be prompted for your username and password.

Username: myusername
Password: 
Login Succeeded

Ensure you are using the correct username and password. For Docker Hub, this is typically your Docker ID. For cloud registries, it might be a specific service account, an IAM user access key, or a token generated by a credential helper (see step 4).

After successful login, attempt your docker push again:

docker push myregistry.com/myusername/myimage:latest

2. Clear Stale Docker Credentials

If re-authenticating doesn't resolve the issue, your local Docker configuration might have stale or conflicting entries. You can explicitly log out and then log back in, or manually clear the relevant entry from your ~/.docker/config.json file.

Option A: docker logout

This command removes the authentication token for a specific registry.

docker logout myregistry.com

Then, proceed with docker login myregistry.com as described in Step 1.

Option B: Manual config.json cleanup

Inspect and, if necessary, remove the specific entry from your ~/.docker/config.json file.

cat ~/.docker/config.json

You'll see a JSON structure with an auths object. Locate the entry for myregistry.com and remove it.

For example, if your config.json looks like this:

{
	"auths": {
		"myregistry.com": {
			"auth": "ZnRlc3Q6cGFzc3dvcmQ=",
			"credsStore": "desktop"
		},
		"anotherregistry.com": {
			"auth": "YWFhYWFhYWFhYWFhYQ=="
		}
	},
	"HttpHeaders": {
		"User-Agent": "Docker-Client/20.10.x (linux)"
	}
}

You would remove the entire "myregistry.com": { ... } block.

Editing ~/.docker/config.json manually requires caution. Malformed JSON will cause Docker client issues. It's often safer to use docker logout or make a backup before editing.

After removing the entry, proceed with docker login myregistry.com as in Step 1.

3. Check System Clock Synchronization (NTP)

Inaccurate system time can cause authentication tokens to appear expired, even if they are valid. Ensure your Alpine Linux system's clock is synchronized using NTP.

1. Install NTP client (if not already installed):

   sudo apk add ntp
   

2. Start and enable NTP service:

   Alpine uses ntpd for time synchronization.

   sudo rc-update add ntpd default
   sudo rc-service ntpd start
   

   Alternatively, force a time sync:

   sudo ntpd -q -g
   

   The -q flag causes ntpd to set the clock and then exit, while -g allows it to set the clock even if the offset is large.

3. Verify the time:

   date
   

   Confirm the date and time are accurate. Then, retry your docker login and docker push.

4. Verify Credential Helper Configuration (for Cloud Registries)

If you're using a cloud provider's container registry (e.g., AWS ECR, Azure ACR) that relies on a credential helper, ensure the helper itself is correctly configured and its underlying authentication is valid.

Example: AWS ECR on Alpine

For AWS ECR, docker login typically involves using the aws-cli to get a temporary password.

1. Install aws-cli:

   sudo apk add py3-pip
   sudo pip3 install awscli
   # Ensure aws-cli is in your PATH. You might need to add ~/.local/bin to PATH.
   export PATH=$PATH:/root/.local/bin # Or wherever pip installs to
   

2. Configure AWS credentials:

   Ensure your AWS CLI is configured with valid credentials (e.g., via aws configure or environment variables like AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN).

3. Generate and use a new ECR login token:

   AWS_ACCOUNT_ID="123456789012" # Replace with your AWS account ID
   AWS_REGION="us-east-1"      # Replace with your AWS region
   
   aws ecr get-login-password --region "${AWS_REGION}" | docker login --username AWS --password-stdin "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
   

   If this command fails, troubleshoot your aws-cli configuration and permissions. Once successful, retry your docker push.

Always ensure your AWS (or other cloud) credentials used by the CLI have the necessary permissions (e.g., ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:InitiateLayerUpload, ecr:UploadLayer, ecr:PutImage) for the target repository.

5. Review Private Registry Configuration (Advanced)

If you are operating your own private Docker registry, investigate its configuration for token lifespan settings.

• Registry Configuration: Consult your registry's documentation. For Docker Distribution (the open-source registry), token expiry is often handled by an authentication proxy (e.g., Nginx, or an identity provider like Keycloak) rather than the registry itself.
• Identity Provider: If your registry uses an external identity provider (e.g., OAuth2/OpenID Connect), check its token expiry settings for the client application associated with your registry.
• Registry Logs: Examine the logs of your private Docker registry and any associated authentication proxies for more specific error messages related to token validation or generation.

6. Environment Variable Check (CI/CD Contexts)

In CI/CD pipelines, authentication might be done using environment variables (e.g., DOCKER_USERNAME, DOCKER_PASSWORD) piped into docker login.

• Verify Variable Validity: Ensure these environment variables are correctly populated with up-to-date, non-expired credentials within your CI/CD runner's environment.
• Secrets Management: If secrets are managed by a vault or secret manager, confirm that the integration is working and pulling the latest credentials. Tokens generated via these methods will still have a lifespan, so ensure the pipeline re-authenticates or refreshes them periodically.

By systematically working through these steps, you should be able to identify and resolve the "authentication token expired" error, restoring your ability to push Docker images from your Alpine Linux environments.