How to fix Error response from daemon: unauthorized: two-factor authentication is required in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 229 views

The 'two-factor authentication is required' error occurs when your Docker Hub account has 2FA enabled, but you're trying to log in with your password instead of a Personal Access Token (PAT). Docker Hub requires access tokens for CLI authentication when two-factor authentication is active.

Quick fix

Fixes Error response from daemon: unauthorized: two-factor authentication is required

# Log out first to clear cached credentials
docker logout

# Log in with your username
docker login -u YOUR_USERNAME
# When prompted for password, paste your Personal Access Token (NOT your password)
  1. Create a Personal Access Token on Docker Hub
  2. Log in using the Personal Access Token
  3. Update CI/CD pipeline credentials
  4. Clear cached credentials from credential helper
docker — error
# Log out first to clear cached credentials
docker logout
# Log in with your username
docker login -u YOUR_USERNAME
# When prompted for password, paste your Personal Access Token (NOT your password)
Error response from daemon: unauthorized: two-factor authentication is required

What this error means

This error indicates that your Docker Hub account has two-factor authentication (2FA) enabled, but you attempted to authenticate using your regular password. When 2FA is enabled on Docker Hub, password-based CLI authentication is disabled for security reasons. Docker Hub implements this restriction because password-based authentication would bypass the second factor of verification. With 2FA enabled, you must use a Personal Access Token (PAT) instead of your password for all CLI operations including `docker login`, `docker pull` for private images, and `docker push`. The authentication flow changes as follows: 1. **Without 2FA**: Username + Password = Access granted 2. **With 2FA**: Username + Password = Error (this error) 3. **With 2FA**: Username + Personal Access Token = Access granted This is a security feature, not a bug. Personal Access Tokens can be scoped with specific permissions and can be revoked individually without affecting your account password.

Typical symptoms

  • Docker login fails with 'unauthorized: two-factor authentication is required'
  • Login started working after enabling 2FA on Docker Hub account
  • Docker login works in web browser but fails in terminal
  • CI/CD pipelines fail at Docker login step after enabling 2FA
  • docker push and docker pull for private repositories stop working
  • Docker Desktop shows authentication error after 2FA enrollment

Common causes

  1. Two-factor authentication was recently enabled on your Docker Hub account
  2. Using your Docker Hub password instead of a Personal Access Token
  3. CI/CD pipeline is configured with password instead of access token
  4. Docker credential helper has cached your old password credentials
  5. Organization security policy requires 2FA and was recently enforced
  6. Docker Desktop session expired after 2FA was enabled

How to fix "Error response from daemon: unauthorized: two-factor authentication is required"

1Create a Personal Access Token on Docker Hub

Since 2FA is enabled on your account, you need to create a Personal Access Token (PAT) to use for CLI authentication.

Create your access token:
1. Go to [hub.docker.com](https://hub.docker.com) and sign in
2. Click your username in the top-right corner
3. Select Account Settings
4. Click Security in the left sidebar
5. Click New Access Token
6. Enter a description (e.g., "CLI access" or "CI/CD pipeline")
7. Select permissions:
 - Read-only - For pulling images only
 - Read, Write - For pushing and pulling images
 - Read, Write, Delete - Full access including image deletion
8. Click Generate
9. Copy the token immediately - it won't be shown again

Important: Store this token securely. Treat it like a password.

2Log in using the Personal Access Token

Now use the access token instead of your password:

bash
# Log out first to clear cached credentials
docker logout

# Log in with your username
docker login -u YOUR_USERNAME
# When prompted for password, paste your Personal Access Token (NOT your password)

Alternatively, use the --password-stdin flag for a non-interactive login:

bash
echo "YOUR_ACCESS_TOKEN" | docker login -u YOUR_USERNAME --password-stdin

Verify the login succeeded:

bash
# Check authentication status
docker info | grep Username

# Test by pulling a private image or listing your repos
docker search YOUR_USERNAME/
3Update CI/CD pipeline credentials

If your CI/CD pipeline is failing, update it to use the Personal Access Token.

GitHub Actions:

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

Update your GitHub secrets:
1. Go to your repository > Settings > Secrets and variables > Actions
2. Update DOCKERHUB_TOKEN with your new Personal Access Token

GitLab CI:

yaml
docker-build:
  script:
    - echo "$DOCKER_TOKEN" | docker login -u "$DOCKER_USER" --password-stdin

Update GitLab CI/CD variables:
1. Go to Settings > CI/CD > Variables
2. Update the DOCKER_TOKEN variable with your Personal Access Token

Jenkins:

groovy
withCredentials([usernamePassword(
  credentialsId: 'docker-hub-creds',
  usernameVariable: 'DOCKER_USER',
  passwordVariable: 'DOCKER_TOKEN'
)]) {
  sh 'echo $DOCKER_TOKEN | docker login -u $DOCKER_USER --password-stdin'
}

Update your Jenkins credentials store with the new access token.

4Clear cached credentials from credential helper

If login still fails after using the correct token, clear your cached Docker credentials:

Check your credential storage method:

bash
cat ~/.docker/config.json

If you see "credsStore": "desktop" or similar, credentials are managed by a credential helper.

Clear credentials on macOS:

bash
# Remove from Docker Desktop credential store
docker logout

# Or manually from Keychain Access app
# Search for "docker" and remove entries for registry-1.docker.io

Clear credentials on Windows:
1. Open Credential Manager (search in Start menu)
2. Click "Windows Credentials"
3. Find entries for docker.io or registry-1.docker.io
4. Remove them
5. Run docker logout and then docker login again

Clear credentials on Linux:

bash
# Log out
docker logout

# Remove Docker config (will require re-login)
rm ~/.docker/config.json

# Or if using pass/secretservice
secret-tool clear server registry-1.docker.io

Then log in again with your Personal Access Token.

5Use Docker Desktop device code flow (alternative)

Docker Desktop and recent CLI versions support a browser-based device code authentication flow that works seamlessly with 2FA:

bash
# Simply run docker login without username/password
docker login

This will:
1. Display a code and URL in your terminal
2. Open your browser (or provide a URL to open)
3. Ask you to enter the code and authenticate via browser
4. Complete authentication including 2FA verification

This flow is more secure and convenient because:
- You authenticate in your browser where 2FA works normally
- No password or token is entered in the terminal
- The session is automatically managed by Docker Desktop

Note: This requires Docker Desktop or a recent version of the Docker CLI.

Advanced notes

### Managing Multiple Access Tokens

Create separate tokens for different purposes for better security:

bash
Token 1: "Personal laptop" - Read, Write
Token 2: "CI/CD production" - Read, Write
Token 3: "CI/CD staging" - Read only
Token 4: "Shared team build server" - Read only

This allows you to:
- Revoke a single token if compromised without affecting others
- Give minimal necessary permissions to each environment
- Track which token is used where

### Token Best Practices

1. Use descriptive names - Include the machine/service name
2. Set expiration dates - For temporary access or contractors
3. Use read-only when possible - If a service only pulls images
4. Rotate tokens periodically - Especially for production CI/CD
5. Never commit tokens - Use environment variables or secrets managers

### Organization 2FA Policies

If you're part of a Docker organization, administrators may enforce 2FA for all members:

- Organization owners can require 2FA under Organization Settings > Security
- Members will receive an email notification to enable 2FA
- A grace period may be given before enforcement
- After enforcement, all CLI authentication must use access tokens

### Docker Desktop SSO Authentication

For organizations using Single Sign-On (SSO):

1. 2FA is typically managed by your identity provider (Okta, Azure AD, etc.)
2. Docker Desktop integrates with SSO for seamless authentication
3. Access tokens still work alongside SSO for CLI access
4. Contact your IT administrator if SSO + 2FA is causing issues

### Recovery Without 2FA Device

If you've lost access to your 2FA device:

1. Use recovery codes provided when 2FA was set up
2. Contact Docker support at hub.docker.com with account verification
3. Recovery codes are stored at: Account Settings > Security > Recovery codes

Always save your recovery codes when enabling 2FA - store them in a password manager or secure location.

### Debugging Authentication Issues

bash
# Check current login status
docker info 2>/dev/null | grep -E "Username|Registry"

# Test token validity by checking rate limits
TOKEN="your-token-here"
curl -s -H "Authorization: Bearer $TOKEN" \
  https://hub.docker.com/v2/repositories/library/alpine/tags | jq '.count'

# View credential storage configuration
cat ~/.docker/config.json | jq '{credsStore, credHelpers}'

Frequently asked questions

What does "Error response from daemon: unauthorized: two-factor authentication is" mean?
This error indicates that your Docker Hub account has two-factor authentication (2FA) enabled, but you attempted to authenticate using your regular password. When 2FA is enabled on Docker Hub, password-based CLI authentication is disabled for security reasons. Docker Hub implements this restriction because password-based authentication would bypass the second factor of verification.
How do I fix "Error response from daemon: unauthorized: two-factor authentication is"?
The 'two-factor authentication is required' error occurs when your Docker Hub account has 2FA enabled, but you're trying to log in with your password instead of a Personal Access Token (PAT). Docker Hub requires access tokens for CLI authentication when two-factor authentication is active.
What causes "Error response from daemon: unauthorized: two-factor authentication is"?
Two-factor authentication was recently enabled on your Docker Hub account Using your Docker Hub password instead of a Personal Access Token CI/CD pipeline is configured with password instead of access token
Is the "Error response from daemon: unauthorized: two-factor authentication is" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading