Kubernetes "ErrImagePull: unauthorized" - missing registry secret in CI

By Daniel Zoghalchali·Latchkey

Pulling from a private registry needs credentials. When the pod has no valid imagePullSecrets (or the secret is wrong), the registry returns 401 and the kubelet reports ErrImagePull / unauthorized.

What this error means

After a deploy, pods show ErrImagePull/ImagePullBackOff and describe reports an unauthorized/401 pulling a private image, even though the tag exists.

Failed to pull image "registry.example.com/api:1.4.2": failed to resolve
reference: pulling from host registry.example.com failed: 401 Unauthorized

Warning  Failed     kubelet  Error: ErrImagePull

Common causes

No imagePullSecret referenced

The pod/service account does not reference a pull secret for the private registry.

Wrong or expired credentials

The docker-registry secret has stale or incorrect credentials.

Secret in the wrong namespace

The pull secret exists but not in the namespace where the pods run.

How to fix it

Create and reference a docker-registry secret

Create the pull secret in the pods' namespace and reference it.

kubectl create secret docker-registry regcred -n prod \
  --docker-server=registry.example.com \
  --docker-username="${{ secrets.REG_USER }}" \
  --docker-password="${{ secrets.REG_PASS }}"
# then add to the pod spec or service account:
#   imagePullSecrets: [{ name: regcred }]

Verify namespace and credentials

1. Ensure the secret lives in the same namespace as the pods.
2. Confirm the credentials work with a manual registry login.
3. Attach the secret to the deploying service account so all its pods inherit it.

How to prevent it

• Manage the pull secret as part of the namespace's bootstrap.
• Attach imagePullSecrets to the service account rather than each pod.
• Rotate registry credentials and update the secret together.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation