Docker Registry Push Failed: Authentication Token Expired on Windows WSL2 Ubuntu

Resolve 'authentication token expired' errors when pushing Docker images from WSL2 Ubuntu to a registry. Re-authenticate and clear stale credentials.

When working with Docker on Windows Subsystem for Linux 2 (WSL2), pushing images to a remote registry is a common operation. However, you might occasionally encounter an authentication token expired error, preventing your pushes. This guide will walk you through the diagnostic and resolution steps to efficiently address this issue.

Symptom & Error Signature

The primary symptom is the failure to push a Docker image to a remote registry, accompanied by an error message indicating that the authentication token has expired. You will typically see output similar to this in your WSL2 terminal:

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

Other variations of the error message might include:

Error response from daemon: Get "https://myregistry.com/v2/": unauthorized: authentication required

or simply

unauthorized: authentication required

but the core problem remains a failure to authenticate due to invalid or expired credentials.

Root Cause Analysis

The "authentication token expired" error fundamentally means that the credentials Docker is attempting to use for authentication with the remote registry are no longer valid. This can happen for several reasons:

1. Session Expiration: Docker login sessions, like many authentication mechanisms, have a time-to-live (TTL). Registries are configured to issue tokens that expire after a certain period (e.g., 8 hours, 24 hours, or longer). If you haven't interacted with the registry for a while, your token might simply have passed its expiration date.
2. Stale Credentials Cache: When you execute docker login, your credentials (or an authentication token derived from them) are stored. On WSL2 with Docker Desktop, these credentials are often managed by a credential helper (e.g., docker-credential-desktop or docker-credential-wincred) which proxies authentication requests to the Windows Credential Manager. If the cached credentials or tokens become outdated, subsequent push attempts will fail.
3. Password Change: If the password for your user account on the remote Docker registry has been changed since your last successful docker login, the stored token will be invalid.
4. Network or Time Skew Issues (Less Common for "Expired"): While less common specifically for an "expired token" message, significant time differences between your WSL2 instance and the registry server can lead to token validation issues. Network problems preventing the credential helper from refreshing tokens could also be a factor.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the "authentication token expired" error. Start with the most common solutions and proceed systematically.

1. Re-authenticate with Docker Login

The most straightforward and frequently effective solution is to log out and then log back into the Docker registry. This forces Docker to discard any expired tokens and acquire a fresh one.

1. Log out from the registry:

   docker logout myregistry.com
   

   Replace myregistry.com with the actual address of your Docker registry (e.g., docker.io for Docker Hub, public.ecr.aws for AWS ECR, etc.).

   If you have logged into multiple registries, repeat this command for each relevant registry. If you are unsure, you can skip logout and proceed directly to login.

2. Log in to the registry again:

   docker login myregistry.com
   

   You will be prompted for your username and password. Enter them carefully.

   Username: myuser
   Password:
   Login Succeeded
   

   After successful login, attempt to push your image again.

2. Inspect and Clear Docker Credential Helper Cache

If re-authenticating doesn't resolve the issue, the problem might lie with a stale credential helper cache, especially when using Docker Desktop with WSL2.

1. Examine your Docker configuration: Check the contents of your ~/.docker/config.json file within your WSL2 instance.

   cat ~/.docker/config.json
   

   Look for entries like credsStore or credHelpers.

   • If credsStore is set to desktop or wincred (common with Docker Desktop): This indicates that Docker is using the Windows Credential Manager to store and retrieve your login details. The stale token is likely cached there.

     Be careful when deleting credentials from Windows Credential Manager. Only remove entries related to Docker or the specific registry causing issues.

     a. Open the Credential Manager in Windows. You can search for it in the Start Menu. b. Select Windows Credentials. c. Look for entries under "Generic Credentials" that start with com.docker.cli, docker, or directly reference your registry (e.g., git:https://myregistry.com). d. Expand the relevant entry and click Remove. Confirm the deletion. e. Once removed, go back to your WSL2 terminal and perform docker login myregistry.com again (as in Step 1) to ensure fresh credentials are saved.

   • If auths entries are directly present (less common with Docker Desktop setups): Your config.json might directly contain auth tokens for registries. While docker logout should clear these, you can manually remove the entry for the problematic registry or, as a last resort, delete the entire config.json file.

     a. To remove a specific registry entry, you can manually edit ~/.docker/config.json with a text editor (like nano or vim) and delete the block for myregistry.com. b. Alternatively, to clear all Docker credentials and force a clean slate (use with caution if you have multiple registry logins configured), delete the file: bash rm ~/.docker/config.json Then, perform docker login myregistry.com again.

3. Verify WSL2 System Time

Time synchronization issues, though less common for specifically "expired token" messages, can sometimes cause authentication failures due to invalid certificate or token validation.

1. Check the current time in your WSL2 instance:

   date
   

   Compare this to the actual current time.

2. Verify detailed time synchronization status:

   timedatectl
   

   This command shows if NTP synchronization is active and the system clock status. WSL2 usually syncs its time with the Windows host, but occasional drifts can occur.

3. Attempt to synchronize the system clock (if significant drift is observed): While WSL2 generally handles time sync automatically, you can try forcing a sync if you suspect an issue.

   sudo hwclock -s
   

   If you have ntpdate installed (you might need sudo apt update && sudo apt install ntpdate), you can also try:

   sudo ntpdate -u pool.ntp.org
   

   After verifying/correcting the time, try docker login and docker push again.

4. Restart Docker Desktop and WSL2 Environment

Sometimes, a full refresh of the Docker Desktop service and the WSL2 environment can resolve underlying communication or state issues.

1. Shut down your WSL2 distribution(s) from Windows: Open a PowerShell or Command Prompt (as administrator is not usually required for this) and run:

   wsl --shutdown
   

   This will terminate all running WSL2 distributions.

2. Restart Docker Desktop: Close Docker Desktop application and then relaunch it. Ensure it starts completely (check the Docker whale icon in the Windows system tray).

3. Re-open your WSL2 terminal: Launch your Ubuntu terminal in WSL2. Docker should automatically start within WSL2 when a Docker command is first executed.

4. Attempt docker login and docker push again.

By systematically following these steps, you should be able to resolve the "authentication token expired" error and successfully push your Docker images from your WSL2 Ubuntu environment to your remote registry.