How to fix rpc error: code = 2 desc = repository does not exist or no pull access in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 110 views

A pod fails to pull a container image from a private registry because the registry credentials are missing, incorrect, or the repository doesn't exist. This occurs with private registries (Azure ACR, AWS ECR, etc.) that require authentication. Fix by creating proper imagePullSecrets with correct credentials.

Quick fix

Fixes rpc error: code = 2 desc = repository does not exist or no pull access

kubectl create secret docker-registry regcred \
  --docker-server=myregistry.azurecr.io \
  --docker-username=<username> \
  --docker-password=<password> \
  -n <pod-namespace>
  1. Create imagePullSecrets for private registry
  2. Reference secret in pod spec
  3. Verify secret exists in pod's namespace
  4. Test credentials locally
kubernetes — error
kubectl create secret docker-registry regcred \
  --docker-server=myregistry.azurecr.io \
  --docker-username=<username> \
  --docker-password=<password> \
  -n <pod-namespace>
rpc error: code = 2 desc = repository does not exist or no pull access

What this error means

When pulling from a private registry, kubelet must authenticate using credentials stored in a Kubernetes secret (imagePullSecrets). If credentials are missing, incorrect, or don't have access to the repository, the pull fails with "repository not found" or "no pull access." This is distinct from a public registry image not existing—the issue is authentication, not availability.

Typical symptoms

  • Pod stuck in ImagePullBackOff state
  • Error shows "repository does not exist or no pull access"
  • Works locally with docker pull but fails in Kubernetes
  • Private registry works for some pods but not others
  • Error appears after credential rotation

Common causes

  1. imagePullSecrets not configured on pod
  2. Secret not in same namespace as pod
  3. Credentials incorrect or expired
  4. Secret has wrong type (not kubernetes.io/dockerconfigjson)
  5. Repository name wrong in image reference
  6. Service account doesn't have secret access

How to fix "rpc error: code = 2 desc = repository does not exist or no pull access"

1Create imagePullSecrets for private registry

Create docker-registry secret:

bash
kubectl create secret docker-registry regcred \
  --docker-server=myregistry.azurecr.io \
  --docker-username=<username> \
  --docker-password=<password> \
  -n <pod-namespace>
2Reference secret in pod spec

Add imagePullSecrets:

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  imagePullSecrets:
  - name: regcred
  containers:
  - name: app
    image: myregistry.azurecr.io/myapp:v1.0
3Verify secret exists in pod's namespace

List secrets:

bash
kubectl get secrets -n <pod-namespace> | grep regcred
kubectl describe secret regcred -n <pod-namespace>

Secret must be in same namespace as pod.

4Test credentials locally

Verify credentials work:

bash
docker login -u <username> -p <password> myregistry.azurecr.io
docker pull myregistry.azurecr.io/myapp:v1.0
5For Azure ACR, use az acr credential show

Get correct credentials:

bash
az acr credential show --name myregistry --query passwords[0].value

Use the output as --docker-password.

6Add secret to service account (optional)

Automatically apply credentials to all pods:

bash
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}']}

This eliminates need to specify imagePullSecrets per pod.

Advanced notes

Kubernetes does NOT use ~/.docker/config.json from local machine; secrets must be explicitly created. Secrets are namespace-scoped. For credential rotation, create new secret and update pods (force rolling restart). For self-signed registries, distribute CA certificates to all nodes. Avoid storing secrets in version control; use a secrets management system. Different cloud registries use different auth: ACR uses username/password, ECR uses temporary tokens, GCR uses service account JSON.

Frequently asked questions

What does "rpc error: code = 2 desc = repository does not exist or no pull access" mean?
When pulling from a private registry, kubelet must authenticate using credentials stored in a Kubernetes secret (imagePullSecrets). " This is distinct from a public registry image not existing—the issue is authentication, not availability.
How do I fix "rpc error: code = 2 desc = repository does not exist or no pull access"?
A pod fails to pull a container image from a private registry because the registry credentials are missing, incorrect, or the repository doesn't exist. This occurs with private registries (Azure ACR, AWS ECR, etc.) that require authentication. Fix by creating proper imagePullSecrets with correct credentials.
What causes "rpc error: code = 2 desc = repository does not exist or no pull access"?
imagePullSecrets not configured on pod Secret not in same namespace as pod Credentials incorrect or expired
Is the "rpc error: code = 2 desc = repository does not exist or no pull access" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading