Troubleshooting ‘Docker Registry Push Failed: Authentication Token Expired’ on Ubuntu 20.04 LTS

Fix Docker registry push errors due to expired authentication tokens on Ubuntu 20.04 LTS. Learn to reauthenticate and resolve Docker login issues quickly.

Introduction

As an experienced Systems Administrator and DevOps engineer, encountering authentication failures when pushing Docker images to a private or public registry is a common yet frustrating issue. One specific error, "authentication token expired," indicates that your Docker client's cached credentials for the registry are no longer valid, preventing successful image uploads. This guide will walk you through diagnosing and resolving this problem on an Ubuntu 20.04 LTS system, ensuring your CI/CD pipelines and manual pushes can proceed without interruption.

Symptom & Error Signature

When attempting to push a Docker image to a remote registry, the operation fails, typically after successfully building or pulling the image. The terminal output will indicate an authentication failure, often explicitly mentioning an expired token or general authorization denial.

Here's a common error signature you might observe:

$ docker push myregistry.example.com/my-org/my-app:latest
The push refers to repository [myregistry.example.com/my-org/my-app]
...
denied: authentication required
Error response from daemon: authorization failed
Error response from daemon: unauthorized: authentication token expired

Alternatively, if you attempt to docker login and the token has expired, you might see:

$ docker login myregistry.example.com
Authenticating with existing credentials...
Error: Your authorization token has expired. Please log in again.

Root Cause Analysis

The "authentication token expired" error, while seemingly straightforward, can stem from a few underlying causes:

1. Time-Limited Tokens: This is the most common reason. Docker registry authentication tokens (be it from a docker login session or a CI/CD system's generated token) are often designed to have a finite lifespan for security reasons. Once this period elapses, the token becomes invalid.
2. Password/Credential Change: The username or password associated with the Docker registry account might have been changed or rotated by an administrator since the last successful login. The client's locally cached credentials (~/.docker/config.json) would then no longer match the active credentials on the registry.
3. Token Revocation: An administrator might have explicitly revoked the specific authentication token or session linked to your client for security or operational reasons.
4. Network/Proxy Interruption During Re-authentication (Less Common for "Expired"): While not directly causing an "expired" token, an intermittent network issue or misconfigured proxy could prevent the Docker client from successfully renewing or re-establishing an authenticated session, making it seem like the old token is the sole issue.
5. Stale Docker Daemon Session: In rare cases, a misbehaving or stale Docker daemon might hold onto outdated authentication information, preventing it from correctly using newly supplied credentials.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the "authentication token expired" error.

#### 1. Verify Current Docker Login Status

First, let's check what Docker thinks its current authentication status is for the registry in question.

cat ~/.docker/config.json

This command will display your Docker configuration file, which stores cached registry credentials. Look for an entry under "auths" that corresponds to myregistry.example.com (or your specific registry hostname). If an auth field exists, it indicates Docker has some credentials cached, but they might be expired or invalid.

{
  "auths": {
    "myregistry.example.com": {
      "auth": "Zn...oZGl" // Base64 encoded username:password
    },
    "docker.io": {
      "auth": "YWJ...sdf",
      "credsStore": "desktop"
    }
  },
  "HttpHeaders": {
    "User-Agent": "Docker-Client/20.10.7 (linux)"
  }
}

The presence of an auth token or a credsStore reference confirms Docker has attempted to store credentials.

#### 2. Re-authenticate with the Docker Registry

The most direct solution for an expired token is to simply log in again. This forces the Docker client to obtain a fresh authentication token from the registry.

docker login myregistry.example.com

You will be prompted to enter your username and password for the registry.

Username: <your-username>
Password: <your-password>
Login Succeeded

• Ensure you use the correct username and a currently valid password or access token for the registry. If your registry uses Multi-Factor Authentication (MFA), you might need to use an API token or an application-specific password rather than your primary account password. Consult your registry's documentation for MFA login procedures.
• After successful login, immediately try your docker push command again.

#### 3. Clear Stale Docker Credentials (If Re-authentication Fails)

If a direct re-authentication doesn't resolve the issue, or if you suspect corrupted local credentials, it's best to explicitly log out and then log in again.

1. Log out from the specific registry:

   docker logout myregistry.example.com
   

   This command removes the cached credentials for myregistry.example.com from ~/.docker/config.json.

2. Manually verify ~/.docker/config.json (Optional but recommended): After docker logout, inspect the ~/.docker/config.json file again to ensure the entry for your registry has been removed or updated. If you find any residual entries or suspect corruption, you can manually edit the file.

   Backup your ~/.docker/config.json before manual editing. Incorrectly modifying this file can disrupt Docker's ability to interact with any registry.

   cp ~/.docker/config.json ~/.docker/config.json.bak
   nano ~/.docker/config.json
   

   Carefully remove the entire block related to myregistry.example.com under the "auths" key.

3. Attempt docker login again:

   docker login myregistry.example.com
   

   Enter your username and password when prompted.

#### 4. Check Registry Service Health and Connectivity

Sometimes, the issue isn't with your token but with the registry being unreachable or having its own issues.

1. Test network connectivity:

   ping -c 4 myregistry.example.com
   

   Ensure you receive responses. If not, check your local network configuration, DNS settings, and firewall rules.

2. Test HTTPS connectivity (basic):

   curl -v https://myregistry.example.com/v2/
   

   This command attempts to access a common Docker registry API endpoint. A successful connection will show HTTP headers, possibly an empty JSON response, but importantly, no connection errors. If you see certificate errors (SSL_CTX_set_default_verify_paths), your system might be missing root certificates or your registry uses a self-signed certificate not trusted by your system.

   If your network requires a proxy for outgoing connections, ensure your Docker daemon and client are configured to use it.

   • For Docker daemon: Configure proxy settings in /etc/systemd/system/docker.service.d/http-proxy.conf or similar.
   • For Docker client: Set HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

#### 5. Verify User Permissions on the Registry

While "token expired" specifically points to authentication, it's always good to confirm that the user account you're using still has the necessary permissions to push to the target repository. This usually involves checking the registry's web interface or contacting your registry administrator.

• Confirm push permissions: Ensure the user account is authorized to push images to the specific repository path (e.g., my-org/my-app).
• Team/Role assignments: Check if the user is part of the correct team or role that grants push access.

#### 6. Restart Docker Daemon (If All Else Fails)

In rare cases, a stale Docker daemon process might be holding onto old session information. Restarting the Docker daemon can clear its internal state and force it to pick up fresh authentication details.

sudo systemctl restart docker
sudo systemctl status docker

Restarting the Docker daemon will stop all running containers on your system. Ensure this is acceptable for your environment or schedule it during a maintenance window. If you have critical services running, proceed with caution.

After the daemon has restarted, attempt your docker login and docker push commands again.

By systematically working through these steps, you should be able to resolve the "Docker registry push failed: authentication token expired" issue on your Ubuntu 20.04 LTS system.