CircleCI "Spin up environment" Image Pull Failed - Fix
The job dies in the "Spin up environment" phase while pulling its container image. Often this is a transient registry hiccup or a Docker Hub rate limit that clears on retry; sometimes the image tag is simply wrong.
What this error means
Before any of your steps run, the job fails pulling the image - a timeout, a 5xx from the registry, or a "toomanyrequests" rate limit. A re-run frequently succeeds, which is the signature of a transient pull failure rather than a config bug.
Spin up environment
Error pulling image cimg/node:20.11:
received unexpected HTTP status: 503 Service Unavailable
# or
toomanyrequests: You have reached your pull rate limit.Common causes
Transient registry error
A momentary 5xx or network blip from the registry interrupts the pull. Nothing is wrong with your config; the same image pulls fine on retry.
Docker Hub anonymous rate limit
Unauthenticated pulls share a rate limit. A busy org hits "toomanyrequests"; authenticating raises the limit and clears the error.
Bad or retired image tag
A non-transient case: the tag does not exist or was removed, so the pull deterministically fails every run.
How to fix it
Authenticate pulls to lift the rate limit
jobs:
build:
docker:
- image: cimg/node:20.11
auth:
username: $DOCKERHUB_USER
password: $DOCKERHUB_PASS
steps: [checkout, { run: npm ci }]Retry transient pulls and pin valid tags
- Re-run the workflow - a one-off 5xx/timeout in "Spin up environment" usually clears.
- Pin a known-good, current image tag so the failure is not a missing tag.
- For repeated rate limits, authenticate or mirror the image to a private registry.
How to prevent it
- Authenticate Docker Hub pulls to avoid anonymous rate limits.
- Pin valid, current image tags for job executors.
- Mirror hot base images to a private registry for high-volume pipelines.