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.
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
First, ensure you're logged in to the correct registry. The login command varies by registry:
Docker Hub:
docker login
# Enter your Docker Hub username and password/access token when promptedAWS ECR:
# 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 IDGoogle Container Registry (GCR):
gcloud auth configure-dockerGitHub Container Registry (ghcr.io):
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdinPrivate/Self-hosted Registry:
docker login your-registry.example.comAfter logging in, verify credentials were stored:
cat ~/.docker/config.jsonThe registry URL in your image tag must exactly match where you authenticated. Check your image tag:
# List your images
docker images
# The image tag format should be:
# registry-url/repository:tagCommon mistakes:
# 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:latestFor AWS ECR, ensure region matches:
# 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:latestDocker 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:
# User credentials
cat ~/.docker/config.json
# Root credentials (used when running docker with sudo)
sudo cat /root/.docker/config.jsonSolution 1: Be consistent with sudo
# 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:latestSolution 2: Add user to docker group (recommended)
# 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:latestAWS ECR authentication tokens expire after 12 hours by default. If you logged in earlier, the token may have expired.
Re-authenticate with AWS ECR:
# 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.comFor CI/CD pipelines, always authenticate before push/pull operations:
# 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:latestCheck token expiration:
# The token is base64 encoded in config.json
# ECR tokens are valid for 12 hours from generationDocker can use credential helpers to store credentials securely. If the helper is misconfigured, authentication fails.
Check your credential store configuration:
cat ~/.docker/config.jsonIf you see "credsStore": "...", or "credHelpers": {...}, Docker is using a credential helper.
Option 1: Reset to basic authentication
# 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.comOption 2: Fix the credential helper
*For Linux with pass:*
# Initialize pass if not done
gpg --gen-key
pass init "your-gpg-id"
# Re-login
docker logout
docker login*For macOS with osxkeychain:*
# 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:*
# Remove https:// prefix from registry URL as a workaround
docker login registry-url-without-httpsWhen 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
docker run -v /root/.docker:/root/.docker -v /var/run/docker.sock:/var/run/docker.sock your-dind-imageOption 2: Login inside the container
# Enter the container
docker exec -it your-container /bin/sh
# Login from within the container
docker login your-registry.example.comOption 3: Pass credentials as environment variables (CI/CD)
# 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:latestOption 4: Use config.json directly
# Create config.json inside the container
mkdir -p ~/.docker
echo '{"auths":{"your-registry.com":{"auth":"BASE64_ENCODED_USER:PASS"}}}' > ~/.docker/config.jsonOn 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:
# Instead of:
docker login https://your-registry.example.com
# Use:
docker login your-registry.example.comFor AWS ECR on Windows:
# 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.comThis is a known issue documented in the AWS ECR troubleshooting guide.
### 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
// 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:
# Install the credential helper
# macOS
brew install docker-credential-helper-ecr
# Linux - download from GitHub releases
# https://github.com/awslabs/amazon-ecr-credential-helper/releasesConfigure in ~/.docker/config.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:
# 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:
# 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:
# 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: regcreddockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec