How to fix no basic auth credentials in Docker

DockerBEGINNERLOW

The 'no basic auth credentials' error occurs when Docker cannot find authentication credentials for a container registry. This typically happens when you haven't logged in to the registry, credentials have expired, or there's a mismatch between your login context and the command execution context.

What this error means

This error indicates that the Docker daemon attempted to access a container registry (such as Docker Hub, AWS ECR, or a private registry) but could not find valid authentication credentials for that registry. When you run `docker push` or `docker pull` against a private repository, Docker needs to authenticate with the registry. It looks for credentials in your Docker configuration file (`~/.docker/config.json`) or in a configured credential helper. If no credentials are found for the target registry, Docker returns this "no basic auth credentials" error. Common scenarios that trigger this error: 1. **Not logged in** - You never ran `docker login` for the target registry 2. **Expired credentials** - AWS ECR tokens expire after 12 hours; other registries may have similar expiration policies 3. **Wrong registry URL** - Credentials exist but for a different registry endpoint 4. **Sudo mismatch** - Logged in as regular user but running Docker with sudo (or vice versa) 5. **Docker-in-Docker** - Credentials on host are not accessible from within the container 6. **Credential helper issues** - The configured credential store (pass, wincred, osxkeychain) isn't working properly

How to fix "no basic auth credentials"

1Log in to the container registry

First, ensure you're logged in to the correct registry. The login command varies by registry:

Docker Hub:

bash

docker login
# Enter your Docker Hub username and password/access token when prompted

AWS ECR:

bash

# Using AWS CLI v2 (recommended)
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Replace:
# - us-east-1 with your region
# - 123456789012 with your AWS account ID

Google Container Registry (GCR):

bash

gcloud auth configure-docker

GitHub Container Registry (ghcr.io):

bash

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Private/Self-hosted Registry:

bash

docker login your-registry.example.com

After logging in, verify credentials were stored:

bash

cat ~/.docker/config.json

2Verify the registry URL matches your image tag

The registry URL in your image tag must exactly match where you authenticated. Check your image tag:

bash

# List your images
docker images

# The image tag format should be:
# registry-url/repository:tag

Common mistakes:

bash

# Wrong - registry URL mismatch
docker login registry-1.docker.io
docker push my-registry.example.com/myimage:latest

# Correct - URLs match
docker login my-registry.example.com
docker push my-registry.example.com/myimage:latest

For AWS ECR, ensure region matches:

bash

# Wrong - authenticated to us-east-1 but pushing to us-west-2
aws ecr get-login-password --region us-east-1 | docker login ...
docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/myrepo:latest

# Correct - regions match
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-west-2.amazonaws.com
docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/myrepo:latest

3Ensure sudo consistency

Docker credentials are stored per-user. If you log in without sudo but run Docker commands with sudo, the credentials won't be found.

Check where your credentials are stored:

bash

# User credentials
cat ~/.docker/config.json

# Root credentials (used when running docker with sudo)
sudo cat /root/.docker/config.json

Solution 1: Be consistent with sudo

bash

# If you use sudo for docker commands, login with sudo too
sudo docker login your-registry.example.com
sudo docker push your-registry.example.com/myimage:latest

Solution 2: Add user to docker group (recommended)

bash

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or run:
newgrp docker

# Now use docker without sudo
docker login your-registry.example.com
docker push your-registry.example.com/myimage:latest

4Refresh expired credentials (AWS ECR)

AWS ECR authentication tokens expire after 12 hours by default. If you logged in earlier, the token may have expired.

Re-authenticate with AWS ECR:

bash

# Get fresh credentials
aws ecr get-login-password --region YOUR_REGION | docker login --username AWS --password-stdin YOUR_ACCOUNT_ID.dkr.ecr.YOUR_REGION.amazonaws.com

For CI/CD pipelines, always authenticate before push/pull operations:

yaml

# GitHub Actions example
- name: Login to Amazon ECR
  id: login-ecr
  uses: aws-actions/amazon-ecr-login@v2

- name: Push image
  run: docker push ${{ steps.login-ecr.outputs.registry }}/my-repo:latest

Check token expiration:

bash

# The token is base64 encoded in config.json
# ECR tokens are valid for 12 hours from generation

5Fix credential helper issues

Docker can use credential helpers to store credentials securely. If the helper is misconfigured, authentication fails.

Check your credential store configuration:

bash

cat ~/.docker/config.json

If you see "credsStore": "...", or "credHelpers": {...}, Docker is using a credential helper.

Option 1: Reset to basic authentication

bash

# Backup and remove the config
mv ~/.docker/config.json ~/.docker/config.json.backup

# Login again - this creates a new config with base64-encoded credentials
docker login your-registry.example.com

Option 2: Fix the credential helper

*For Linux with pass:*

bash

# Initialize pass if not done
gpg --gen-key
pass init "your-gpg-id"

# Re-login
docker logout
docker login

*For macOS with osxkeychain:*

bash

# Check Keychain Access for Docker entries
# Delete any corrupted Docker credentials
security delete-generic-password -s "Docker Credentials"

# Re-login
docker login

*For Windows with wincred:*

bash

# Remove https:// prefix from registry URL as a workaround
docker login registry-url-without-https

6Handle Docker-in-Docker scenarios

When running Docker inside a container (Docker-in-Docker), credentials from the host are not automatically available inside the container.

Option 1: Mount the credentials directory

bash

docker run -v /root/.docker:/root/.docker -v /var/run/docker.sock:/var/run/docker.sock your-dind-image

Option 2: Login inside the container

bash

# Enter the container
docker exec -it your-container /bin/sh

# Login from within the container
docker login your-registry.example.com

Option 3: Pass credentials as environment variables (CI/CD)

yaml

# GitLab CI example
docker-job:
  image: docker:latest
  services:
    - docker:dind
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
    - docker push $CI_REGISTRY_IMAGE:latest

Option 4: Use config.json directly

bash

# Create config.json inside the container
mkdir -p ~/.docker
echo '{"auths":{"your-registry.com":{"auth":"BASE64_ENCODED_USER:PASS"}}}' > ~/.docker/config.json

7Remove https:// prefix from registry URL (Windows workaround)

On Windows, some versions of Docker have a bug where the wincred credential manager doesn't properly handle URLs with the https:// scheme.

Workaround - login without the scheme:

bash

# Instead of:
docker login https://your-registry.example.com

# Use:
docker login your-registry.example.com

For AWS ECR on Windows:

bash

# Ensure no https:// prefix
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

This is a known issue documented in the AWS ECR troubleshooting guide.

Advanced notes

### Understanding Docker's Credential Flow

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

1. Extracts the registry hostname from the image reference
2. Looks up credentials in ~/.docker/config.json
3. If credsStore is set, queries the credential helper
4. If credHelpers is set with a matching registry, uses that specific helper
5. Falls back to the auths section for base64-encoded credentials

json

// Example ~/.docker/config.json
{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "dXNlcm5hbWU6cGFzc3dvcmQ="
    }
  },
  "credsStore": "desktop",
  "credHelpers": {
    "gcr.io": "gcloud",
    "123456789012.dkr.ecr.us-east-1.amazonaws.com": "ecr-login"
  }
}

### AWS ECR Credential Helper

For AWS ECR, consider using the Amazon ECR Docker Credential Helper for automatic token refresh:

bash

# Install the credential helper
# macOS
brew install docker-credential-helper-ecr

# Linux - download from GitHub releases
# https://github.com/awslabs/amazon-ecr-credential-helper/releases

Configure in ~/.docker/config.json:

json

{
  "credHelpers": {
    "public.ecr.aws": "ecr-login",
    "123456789012.dkr.ecr.us-east-1.amazonaws.com": "ecr-login"
  }
}

### Debugging Authentication

Enable Docker debug mode to see detailed authentication flow:

bash

# Set debug mode
export DOCKER_CLI_EXPERIMENTAL=enabled
export DOCKER_BUILDKIT=1

# Run with debug output
docker --debug push your-image:tag 2>&1 | grep -i auth

### Multi-Architecture Builds with BuildKit

When using docker buildx for multi-architecture builds, ensure credentials are available:

bash

# Create and use a builder
docker buildx create --use

# Build and push (requires login first)
docker login your-registry.example.com
docker buildx build --platform linux/amd64,linux/arm64 -t your-registry.example.com/image:tag --push .

### Kubernetes ImagePullSecrets

If pods are failing with "no basic auth credentials" in Kubernetes:

bash

# Create a secret from your Docker config
kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=$HOME/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson

# Or create manually
kubectl create secret docker-registry regcred \
  --docker-server=your-registry.example.com \
  --docker-username=username \
  --docker-password=password \
  [email protected]

# Reference in pod spec
spec:
  imagePullSecrets:
    - name: regcred

How to fix no basic auth credentials in Docker

What this error means

Typical symptoms

Common causes

How to fix "no basic auth credentials"

Advanced notes

Related errors

Official resources & further reading