Troubleshooting ‘Docker Registry Push Failed: Authentication Token Expired’ on macOS

Resolve Docker registry push errors on macOS due to expired authentication tokens. Learn to clear caches, re-authenticate, and configure Docker Desktop.

Pushing Docker images to a remote registry is a routine task in any CI/CD pipeline or local development workflow. When this critical operation fails with an "authentication token expired" error, it can halt progress and cause significant frustration, especially in a macOS local development environment where credential management is often handled automatically by Docker Desktop's integrations. This guide provides a detailed, technical walkthrough to diagnose and resolve this common issue.

Symptom & Error Signature

When attempting to push a Docker image to a remote registry (e.g., Docker Hub, AWS ECR, GitLab Container Registry, private registries) from your macOS machine, the operation fails, and you observe output similar to the following in your terminal:

$ docker push myregistry.com/myusername/myimage:latest
The push refers to repository [myregistry.com/myusername/myimage]
An image does not exist locally with the tag: myregistry.com/myusername/myimage
OR
denied: Your authorization token has expired. Reauthenticate and try again.
OR
Error response from daemon: Get "https://myregistry.com/v2/": unauthorized: authentication required
OR
Error response from daemon: authorization token expired

While the exact wording may vary slightly depending on the registry, the core message points to an issue with your authentication credentials, specifically that the token used for authorization has become invalid.

Root Cause Analysis

The "authentication token expired" error primarily stems from issues with how Docker Desktop and the Docker CLI manage and store your registry credentials on macOS. Here are the most common underlying reasons:

1. Expired Docker Login Session: Direct docker login sessions have a finite lifespan. If you haven't logged in for a while, or if the registry itself has aggressive token expiration policies, your token will simply become invalid.
2. Stale Credentials in macOS Keychain: Docker Desktop, by default, leverages the macOS Keychain Access utility as its credential store via the osxkeychain credential helper. This helper caches tokens to prevent frequent re-authentication prompts. If the cached token in Keychain Access becomes stale, corrupted, or out of sync with the actual token's validity, Docker will fail to authenticate.
3. Corrupted ~/.docker/config.json: This file stores Docker CLI configuration, including references to credential helpers and potentially base64-encoded authentication strings. An incorrectly formatted or outdated entry for a specific registry can lead to authentication failures.
4. Docker Desktop Internal State Issues: Occasionally, Docker Desktop's internal processes or its credential helper can get into an inconsistent state, preventing it from correctly retrieving or refreshing authentication tokens.
5. Network or Proxy Interference: While less common for "token expired" specifically, network interruptions, VPNs, or misconfigured proxies could theoretically prevent Docker from renewing or validating tokens with the registry.

Step-by-Step Resolution

Follow these steps in order, testing after each one, to resolve the authentication token expiration issue.

1. Re-authenticate with docker login

This is the most straightforward and often effective solution. It forces Docker to obtain a new authentication token from the registry.

1. Open your terminal.

2. Execute the docker login command for the registry you're trying to push to. If you're pushing to Docker Hub, you typically don't need to specify the registry URL. For private registries, always provide the full URL.

   # For Docker Hub
   docker login
   
   # For a private registry (e.g., myregistry.com)
   docker login myregistry.com
   

3. Enter your username and password when prompted. Ensure you use the correct credentials for the registry.

   Username: your_docker_username
   Password:
   Login Succeeded
   

4. Attempt your docker push again.

2. Clear Stale Credentials from macOS Keychain

If re-authenticating doesn't work, the macOS Keychain likely holds a stale or corrupted entry.

1. Open Keychain Access: You can find it in Applications/Utilities/Keychain Access.app or by searching with Spotlight (Cmd+Space and type "Keychain Access").
2. Search for Docker credentials: In the search bar within Keychain Access, type docker or the name of your registry (e.g., myregistry.com, ecr).
3. Locate the relevant entry: Look for entries labeled docker or DOCKER followed by the registry URL (e.g., Docker Credential Helper cached auth info for myregistry.com).
4. Delete the entry: Right-click on the relevant entry and select Delete "entry_name". Confirm the deletion.
5. Restart Docker Desktop: Completely quit Docker Desktop and then restart it.
6. Re-authenticate: Perform docker login as described in Step 1.
7. Attempt your docker push again.

Deleting entries from Keychain Access for Docker will require you to re-authenticate with those registries. Ensure you have your credentials readily available before proceeding.

3. Inspect and Clean ~/.docker/config.json

The config.json file dictates how Docker handles credentials. A malformed or outdated entry can cause issues.

1. Backup your config.json:

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

2. Inspect the contents:

   cat ~/.docker/config.json
   

   You should see something similar to this:

   {
       "auths": {
           "https://index.docker.io/v1/": {},
           "myregistry.com": {}
       },
       "credsStore": "osxkeychain",
       "currentContext": "default"
   }
   

   Notice the "credsStore": "osxkeychain" line. This confirms Docker Desktop is using Keychain Access. If there are auths entries with base64 encoded credentials that look suspicious or are for the problematic registry, these might be causing issues.

3. Log out from the problematic registry: This explicitly removes its entry (or an old, cached entry) from config.json and potentially from the credential store.

   # For Docker Hub
   docker logout
   
   # For a private registry
   docker logout myregistry.com
   

4. Manually edit config.json (if necessary): If docker logout doesn't clear the problematic entry, or if the file is malformed, you might need to edit it.

   nano ~/.docker/config.json
   

   Carefully remove the auths entry block for the registry causing issues. Save and exit.

Directly editing ~/.docker/config.json requires caution. Incorrect JSON syntax will break Docker's ability to manage credentials. Always back up the file first.

5. Restart Docker Desktop.
6. Re-authenticate: Perform docker login as described in Step 1.
7. Attempt your docker push again.

4. Restart Docker Desktop

Sometimes, Docker Desktop's internal processes or the credential helper itself can get into an unstable state. A full restart can resolve these transient issues.

1. Quit Docker Desktop: Click the Docker icon in your macOS menu bar, then select Quit Docker Desktop.
2. Wait a few seconds.
3. Start Docker Desktop: Launch it again from your Applications folder.
4. Re-authenticate (if you haven't already in previous steps): Perform docker login for your registry.
5. Attempt your docker push again.

5. Verify Network Connectivity and Proxy Settings

While less directly related to an "expired token," ensuring robust network connectivity is crucial, as token renewal and validation require reaching the registry's authentication endpoints.

1. Check basic connectivity:

   ping myregistry.com
   curl -I https://myregistry.com/v2/ # Check for HTTP headers, expecting 401 Unauthorized for initial access
   

2. Review proxy settings: If you're behind a corporate proxy or using a VPN, ensure Docker Desktop is correctly configured with your proxy settings.
   • Open Docker Desktop Preferences/Settings.
   • Navigate to the "Resources" > "Proxies" section.
   • Ensure "Manual proxy configuration" is correctly set if required by your network environment.
3. Temporarily disable VPN: If you suspect your VPN might be interfering, try temporarily disabling it and then performing docker login and docker push.

By systematically applying these troubleshooting steps, you should be able to resolve the "Docker registry push failed authentication token expired" error on your macOS local environment and get back to your containerized development workflow.