Walks from the exact pull error through the pod's imagePullSecrets to the actual Secret content, fixing a missing secret reference, an expired token, or a wrong registry host/namespace. It explicitly does not cover a missing or mistyped image tag ('manifest unknown', 'repository does not exist') — that's a different error and a different fix — and it is not a general Docker registry-login guide: a successful `docker pull` on a developer's laptop proves the credentials are valid outside the cluster, it does not prove the pod itself has them wired up.
Unverifiedno reproductions yetWhy this confidence?8 steps. Every step is written out below in full — the interactive version simply follows the branches for you.
A working docker pull of the same image on a developer's laptop is a red herring for this branch of the problem — it only proves the registry credentials are valid somewhere, not that the pod has them. Kubelet pulls images using the pod's own imagePullSecrets (or its ServiceAccount's), which is a completely separate credential path.
What happens next
Confirm the Events line is actually an authentication/authorization failure and not a different kind of pull error.
kubectl describe pod <pod-name> -n <namespace>Expected result
Warning Failed 8s (x4 over 47s) kubelet Failed to pull image "registry.example.com/team/app:1.4.2": rpc error: code = Unknown desc = failed to pull and unpack image "registry.example.com/team/app:1.4.2": failed to resolve reference: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failedWhat happens next
Check whether the pod spec (directly, or via its ServiceAccount) has any imagePullSecrets configured at all.
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.imagePullSecrets}'Expected result
[]What happens next
If the error instead reads something like 'manifest unknown', 'repository does not exist' without an authorization message, or names a tag that clearly doesn't exist, the image reference itself is wrong. Fix the image name/tag in the pod spec — the credential-wiring steps below won't help.
imagePullSecrets are namespace-scoped — a secret created in one namespace is invisible to pods in another, which is one of the most common reasons this looks broken despite 'having a secret'.
kubectl get secret <secret-name> -n <namespace> --type=kubernetes.io/dockerconfigjson -o jsonpath='{.data.\.dockerconfigjson}' | base64 -dExpected result
{"auths":{"registry.example.com":{"username":"deploy-bot","password":"***","auth":"ZGVwbG95LWJvdDoqKio="}}}What happens next
If nothing is referenced at all, the most durable fix is attaching the secret to the ServiceAccount so every pod in the namespace picks it up automatically, rather than editing every pod spec individually. Any pod already running still needs to be deleted and recreated to pick this up.
Changes system or service state. Review before running.
Adds the image pull secret to the namespace's default ServiceAccount; pods created after this pick it up automatically, but the current failing pod still needs to be deleted (or its Deployment rolled) to actually retry the pull with it.
kubectl patch serviceaccount default -n <namespace> -p '{"imagePullSecrets": [{"name": "regcred"}]}'The secret exists, is in the right namespace, and names the right registry host, but the pull still fails as unauthorized — the embedded token/password has most likely expired or been rotated since the secret was created. Recreate it with a currently valid credential.
Touches credentials or secrets. Never paste real secrets into a shared terminal.
Overwrites the existing 'regcred' Secret in this namespace with the newly supplied registry credentials; anyone able to read Secrets in this namespace can read the embedded password after this runs.
kubectl create secret docker-registry regcred \
--docker-server=registry.example.com \
--docker-username=<username> \
--docker-password=<token> \
--docker-email=<email> \
-n <namespace> \
--dry-run=client -o yaml | kubectl apply -f -Recreate the secret in the correct namespace with --docker-server set to exactly the host used in the image reference (for example ghcr.io if the image is ghcr.io/org/app:tag) — a mismatched host is silently ignored by kubelet's credential lookup.
Touches credentials or secrets. Never paste real secrets into a shared terminal.
Creates or overwrites the 'regcred' Secret in this namespace with the supplied registry credentials; anyone able to read Secrets in this namespace can read the embedded password after this runs.
kubectl create secret docker-registry regcred \
--docker-server=<exact-registry-host> \
--docker-username=<username> \
--docker-password=<token> \
--docker-email=<email> \
-n <namespace> \
--dry-run=client -o yaml | kubectl apply -f -What would strengthen it: 6 more independent reproductions. Reproductions from 3 more distinct environments.