Skip to main content

Image Pull Errors

Before You Change Anything

Start with inspection and narrowing steps first. Some fixes in debugging pages mutate shared resources, so separate observation from recovery.

Use this page when a pod never gets to the application startup phase because Kubernetes cannot fetch its image.

The two most common causes in the Crawbl cluster are DOCR access problems and Bitnami tag unavailability.

Symptoms​

kubectl get pods -n backend

Output shows:

NAME                            READY   STATUS             RESTARTS   AGE
orchestrator-6f8b4c9d7-x2k4p   0/1     ImagePullBackOff   0          2m

Or ErrImagePull in the status column.

Check the events for the specific error:

kubectl describe pod -n backend -l app=orchestrator

Look for messages like:

  • unauthorized: authentication required
  • manifest unknown
  • tag not found

Quick read:

  • unauthorized usually points to an auth or registry-access problem
  • manifest unknown or tag not found usually means the image tag does not exist anymore

DOCR Pull Secret Expiry​

DOKS clusters use registryIntegration=true for native DOCR access, so per-namespace pull secrets are usually not needed.

If that setting is unfamiliar, it means the cluster nodes already have permission to pull from DigitalOcean Container Registry (DOCR).

However, if you are pulling images locally or the integration token has expired, re-authenticate:

doctl registry login

If the cluster nodes cannot pull images from DOCR:

# Verify the registry integration is active
doctl kubernetes cluster registry list

# If missing, re-add it
doctl registry kubernetes-manifest | kubectl apply -f -

For local Docker operations:

# Re-authenticate with DOCR
doctl registry login
docker pull registry.digitalocean.com/crawbl/crawbl-platform:dev

Bitnami Tag Issues​

Bitnami stopped publishing semver-pinned tags (like bitnami/redis:8.2.1-debian-12-r0) on Docker Hub. If a pod fails to pull a Bitnami image:

Fix Option 1: Pin by Digest​

In the component's Helm values (components/<name>/envs/dev.yaml), pin the image by SHA256 digest:

image:
  digest: sha256:<current-digest>

To find the current digest:

docker pull bitnami/redis:latest
docker inspect --format='{{index .RepoDigests 0}}' bitnami/redis:latest

Fix Option 2: Upgrade the Vendored Chart​

Upgrade to the latest chart version, which defaults to pulling the latest tag:

rm -rf components/redis/chart
helm pull bitnami/redis --version <latest-version> \
  --untar -d components/redis/chart/

See Upgrade a Vendored Chart for the full procedure.

Wrong Image Tag​

If the image tag does not exist in DOCR (e.g., a typo or a failed CI build):

# List available tags for an image
doctl registry repository list-tags crawbl-platform

Verify the tag in the ArgoCD apps values:

# Check the current tag in the values file
rg -n "repository:|tag:" crawbl-argocd-apps/components/orchestrator/chart/values.yaml

If the tag is wrong, update the values file, commit, and push. ArgoCD then syncs the corrected image.

Quick Reference​

ProblemFix
DOCR auth failure (local)doctl registry login
DOCR auth failure (cluster)doctl registry kubernetes-manifest | kubectl apply -f -
Bitnami tag not foundPin by digest or upgrade the vendored chart
Wrong image tagCheck doctl registry repository list-tags <image>, fix values
Image not builtCheck CI — the build job may have failed

What's next: Auth Failures

🔗 Terms On This Page

If a term below is unfamiliar, open its glossary entry. For the full list, go to Internal Glossary.

  • DOCR: DigitalOcean Container Registry, where Crawbl stores container images.
  • DOKS: DigitalOcean Kubernetes, the managed Kubernetes service used for the Crawbl cluster.
  • Helm Chart: A packaged set of Kubernetes templates and values used to deploy an application.
  • ArgoCD: The GitOps deployment system that keeps the cluster aligned with what is committed in Git.