How to fix Error response from daemon: unauthorized: authentication required in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 367 views

The 'unauthorized: authentication required' error occurs when Docker cannot authenticate with a container registry. This typically happens when you haven't logged in, your credentials have expired, or you're pushing to the wrong registry URL.

Quick fix

Fixes Error response from daemon: unauthorized: authentication required

# Log in to Docker Hub (default registry)
docker login

# You'll be prompted for username and password
# For Docker Hub, use your username (not email) and password or access token

Log in to Docker Hub or your private registry
Use the correct registry URL for Docker Hub
Verify your image name matches your username
Reset credentials and log in again

docker — error

$# Log in to Docker Hub (default registry)
docker login
# You'll be prompted for username and password
# For Docker Hub, use your username (not email) and password or access token
Error response from daemon: unauthorized: authentication required

What this error means

This error message indicates that the Docker daemon attempted to access a container registry (such as Docker Hub, GitHub Container Registry, or a private registry) but was rejected because valid authentication credentials were not provided. The Docker registry uses a token-based authentication system. When you try to push or pull an image, the registry checks whether your request includes a valid authentication token. If the token is missing, expired, or invalid, the registry responds with this "unauthorized: authentication required" error. This error commonly occurs in several scenarios: 1. **You haven't logged in** - You need to run `docker login` before accessing private repositories 2. **Credentials have expired** - Docker Hub tokens and session credentials expire over time 3. **Wrong registry URL** - You're authenticated to one registry but trying to access another 4. **Image name mismatch** - The image name doesn't match your authenticated username/organization 5. **Private image on free tier** - You may have exceeded Docker Hub's private repository limits

Typical symptoms

Docker push fails immediately after successful build
Docker pull fails for private images despite prior login
CI/CD pipelines fail at the push or pull stage
Error occurs even after running 'docker login' successfully
Commands work with sudo but fail without it
Error appears when pushing to Docker Hub for the first time

Common causes

Not logged in to the container registry with 'docker login'
Using 'sudo docker push' without having run 'sudo docker login'
Docker Hub access token has been revoked or expired
Image name doesn't match your Docker Hub username (e.g., pushing 'myapp' instead of 'username/myapp')
Pushing to Docker Hub with the wrong registry URL
Credentials stored in a different location (sudo vs non-sudo)
System date/time is significantly incorrect, causing token validation to fail
Docker Hub private repository limit exceeded on free tier
Registry is behind a proxy or firewall blocking authentication

How to fix "Error response from daemon: unauthorized: authentication required"

1Log in to Docker Hub or your private registry

The most common fix is to authenticate with the registry before pushing or pulling images.

bash

# Log in to Docker Hub (default registry)
docker login

# You'll be prompted for username and password
# For Docker Hub, use your username (not email) and password or access token

Important: If you use sudo for Docker commands, you must also log in with sudo:

bash

# Credentials are stored separately for root and your user
sudo docker login

After logging in successfully, you should see:

bash

Login Succeeded

2Use the correct registry URL for Docker Hub

Sometimes the default Docker Hub login doesn't work properly. Try specifying the registry URL explicitly:

bash

# Log in with the explicit Docker Hub registry URL
docker login -u your-username https://index.docker.io/v1/

This ensures Docker authenticates with the correct registry endpoint. The index.docker.io/v1/ URL is Docker Hub's official authentication endpoint.

For private registries, use their specific URL:

bash

# AWS ECR
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.region.amazonaws.com

# Azure Container Registry
docker login myregistry.azurecr.io

# Google Container Registry
docker login gcr.io

3Verify your image name matches your username

Docker Hub requires that the image name includes your username or organization as a prefix. If you try to push an image without this prefix, authentication will fail.

bash

# Wrong - image name doesn't include username
docker push myapp:latest
# Error: unauthorized: authentication required

# Correct - tag the image with your username first
docker tag myapp:latest yourusername/myapp:latest
docker push yourusername/myapp:latest

For organizations, use the organization name:

bash

docker tag myapp:latest myorganization/myapp:latest
docker push myorganization/myapp:latest

To check your current Docker Hub username:

bash

cat ~/.docker/config.json | grep -A2 "index.docker.io"

4Reset credentials and log in again

If you're still seeing the error after logging in, your stored credentials may be corrupted or outdated. Clear them and log in fresh:

bash

# Log out from Docker Hub
docker logout

# Log out from a specific registry (if applicable)
docker logout registry.example.com

# Remove the credentials file (backup first)
mv ~/.docker/config.json ~/.docker/config.json.backup

# Log in again
docker login

On macOS and Windows, Docker Desktop stores credentials in the system keychain. You may need to clear those as well:
- macOS: Open Keychain Access, search for "docker", and delete related entries
- Windows: Use Credential Manager to remove Docker-related credentials

5Use a Docker Hub access token instead of password

Docker Hub recommends using access tokens instead of your account password. Tokens are more secure and can be revoked individually.

1. Go to https://hub.docker.com/settings/security
2. Click "New Access Token"
3. Give it a descriptive name and select permissions
4. Copy the token (you won't see it again)

Use the token to log in:

bash

docker login -u yourusername
# When prompted for password, paste your access token

Or use stdin for automated scripts:

bash

echo "$DOCKER_TOKEN" | docker login -u yourusername --password-stdin

6Check system date and time

Authentication tokens have expiration timestamps. If your system clock is significantly off, the registry may reject your authentication.

bash

# Check current system time
date

# Compare with actual time
# If off by more than a few minutes, sync the clock

# On Linux with systemd
sudo timedatectl set-ntp true
sudo systemctl restart systemd-timesyncd

# On macOS
sudo sntp -sS time.apple.com

# On Windows (PowerShell as Admin)
w32tm /resync

Docker Desktop on macOS and Windows manages its own clock, which can sometimes drift from the host. Restarting Docker Desktop can help resync the time.

7Check Docker Hub subscription and private repository limits

Docker Hub free tier has limitations on private repositories. If you're trying to push a new private image and have reached your limit, you'll see an authentication error.

Check your current usage:
1. Go to https://hub.docker.com/
2. Click on your profile > Account Settings
3. Review your subscription plan and repository limits

Free tier allows:
- Unlimited public repositories
- Limited private repositories (check current limits on Docker Hub)

If you've exceeded limits, you can:
1. Delete unused private repositories
2. Make some repositories public
3. Upgrade to a paid Docker Hub subscription

Advanced notes

### Understanding Docker's Authentication Flow

When Docker needs to authenticate with a registry, it follows this process:

1. Client requests the image from the registry
2. Registry returns a 401 Unauthorized with a WWW-Authenticate header
3. Client requests a bearer token from the auth service
4. Auth service validates credentials and returns a token
5. Client retries the original request with the bearer token

Failures can occur at any step in this process.

### Debugging Authentication Issues

Check your stored credentials:

bash

cat ~/.docker/config.json

The auths section shows stored credentials:

json

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "base64-encoded-credentials"
    }
  }
}

If you see credsStore instead of credentials, Docker is using a credential helper (like macOS Keychain or Windows Credential Manager).

### CI/CD Pipeline Configuration

For CI/CD systems, ensure credentials are properly configured:

GitHub Actions:

yaml

- name: Login to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

GitLab CI:

yaml

before_script:
  - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY

### Network and Proxy Issues

If you're behind a corporate proxy, Docker may have trouble reaching the auth service:

bash

# Set proxy for Docker daemon (Linux)
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo cat > /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

### Self-Hosted Registry Authentication

For self-hosted Docker registries, ensure:

1. TLS is properly configured (Docker requires HTTPS for authentication)
2. The registry is reachable from your Docker host
3. You're using the correct port in the login command

bash

# Include the port if your registry uses a non-standard port
docker login registry.example.com:5000

For registries using self-signed certificates, you may need to add them to Docker's trusted certificates or configure the registry as insecure (not recommended for production).

Frequently asked questions

What does "Error response from daemon: unauthorized: authentication required" mean?: This error message indicates that the Docker daemon attempted to access a container registry (such as Docker Hub, GitHub Container Registry, or a private registry) but was rejected because valid authentication credentials were not provided. The Docker registry uses a token-based authentication system. When you try to push or pull an image, the registry checks whether your request includes a valid authentication token.
How do I fix "Error response from daemon: unauthorized: authentication required"?: The 'unauthorized: authentication required' error occurs when Docker cannot authenticate with a container registry. This typically happens when you haven't logged in, your credentials have expired, or you're pushing to the wrong registry URL.
What causes "Error response from daemon: unauthorized: authentication required"?: Not logged in to the container registry with 'docker login' Using 'sudo docker push' without having run 'sudo docker login' Docker Hub access token has been revoked or expired
Is the "Error response from daemon: unauthorized: authentication required" error serious?: It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
💬
Stack Overflow - Docker unauthorized upon push(Stack Overflow)
📖
Docker login command reference(Official Docs)
🐙
GitHub Issue - unauthorized upon pulling public image(GitHub)
💬
Docker Forums - Push error unauthorized(Stack Overflow)
📖
Docker Registry Authentication API(Official Docs)

How to fix Error response from daemon: unauthorized: authentication required in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "Error response from daemon: unauthorized: authentication required"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading