Introduction

Docker returns unauthorized: authentication required when it can reach the registry but the registry rejects the credentials or access scope for the requested image. This problem appears in local development, CI pipelines, and Kubernetes clusters because all of them ultimately rely on the same registry authentication chain: the right registry hostname, the right credentials, and the right repository permissions.

Symptoms

  • docker pull fails with unauthorized: authentication required
  • Authentication succeeds for one image or repository but not another
  • Kubernetes Pods fall into ImagePullBackOff with registry auth errors
  • A registry migration or token rotation broke previously working pulls

Common Causes

  • Docker is logged into the wrong registry hostname
  • The token or credentials do not grant access to the specific repository path
  • A credential helper is misconfigured or returning stale credentials
  • Kubernetes is using an outdated image pull secret

Step-by-Step Fix

  1. 1.Log in to the exact registry hostname used by the image
  2. 2.Authentication is registry-host specific. Logging into one hostname does not authenticate pulls from another similar-looking endpoint.
bash
docker login registry.example.com
  1. 1.Inspect stored Docker credentials
  2. 2.Verify that ~/.docker/config.json contains the registry entry you actually need.
bash
cat ~/.docker/config.json
  1. 1.Recheck token scope or repository permissions
  2. 2.A token that can authenticate may still be unauthorized for the target repository or namespace.
  3. 3.Refresh Kubernetes image pull secrets if the problem is cluster-side
  4. 4.A stale secret or wrong registry server name is a common cause of ImagePullBackOff.
bash
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass

Prevention

  • Use the exact registry hostname consistently in image references and login steps
  • Rotate and refresh CI or Kubernetes credentials together with registry token changes
  • Prefer supported credential helpers for cloud registries
  • Test private image pulls immediately after permission or registry changes