Coolify Docker Hub pull rate limit: fix 429 safely

A Coolify deployment can fail while pulling a base image or replacement image with toomanyrequests, “You have reached your pull rate limit”, or a bare HTTP 429 Too Many Requests. Repeatedly pressing Deploy usually makes the incident noisier. The useful question is which limit fired, from which server identity, during which pull.

Docker Hub currently documents separate pull-usage and abuse controls. Unauthenticated pulls are counted by public IPv4 address or IPv6 /64; authenticated Personal accounts receive a larger pull allowance, while paid authenticated tiers have different treatment. A short bare 429 instead points to the abuse limit and should trigger investigation of a looping client or pipeline—not a faster retry loop.

Fix the identity and pull pattern first. A successful retry that uses the same anonymous shared address is only a temporary reprieve.

Recognise the two 429 failures

1. Preserve the failed deployment evidence

Open the exact Coolify deployment and record its deployment ID, source commit, server, final successful step, and complete registry error. Distinguish a build-time base-image pull such as FROM nginx:alpine from the deployment server pulling a prebuilt application image. Those operations may happen on different machines and under different operating-system users.

On each involved server, inspect the configured identity without printing credentials:

whoami
printf 'home=%s\n' "$HOME"
docker version --format 'client={{.Client.Version}} server={{.Server.Version}}'
docker info --format '{{json .RegistryConfig.Mirrors}}'

test -f "$HOME/.docker/config.json" && echo 'docker config exists'
docker image ls --digests --format \
  'table {{.Repository}}\t{{.Tag}}\t{{.Digest}}\t{{.CreatedSince}}'

Do not paste ~/.docker/config.json into a ticket or log. Its authentication entries are encoded, not safely encrypted secrets. Also avoid exposing registry tokens through command arguments, process listings, or shell history.

2. Find which server is pulling

Coolify may build and deploy on one server, or use a separate build server that pushes a completed image for another server to pull. A Docker Image application skips source cloning and building: the deployment server pulls the configured image directly. A Dockerfile build normally pulls every uncached base image on the build host.

• One-server build: authenticate the Coolify server user on that server.
• Separate build server: authenticate the build server for its base images and the deployment server for the published application image.
• Docker Swarm: every node that may run the service needs registry reachability and appropriate authentication.
• Several VPSs behind one NAT: anonymous Docker Hub usage may be aggregated by their shared public address.
• IPv6: Docker documents anonymous accounting at the /64 boundary, not necessarily per individual host address.

Repository credentials are separate from registry credentials. A GitHub App or deploy key may clone private source successfully while Docker Hub or GHCR image pulls remain anonymous or unauthorized.

3. Reproduce one pull deliberately

After stopping automatic retry loops, run one pull as the same user and on the same machine Coolify uses. Use the exact failing reference from the deployment log:

docker pull docker.io/library/IMAGE:VERSION

Do not substitute latest; a different manifest may be cached or use different platform layers. If the one controlled pull reproduces the documented pull-limit message, authentication is the narrowest first repair. If it returns only a bare 429, audit repeated deployment hooks, CI matrices, health scripts, image-watch tools, and other Docker Hub API clients before retrying.

4. Authenticate the correct Coolify server user

Current Coolify documentation exposes registry logins under Registries or Servers → your server → Registries. Select Docker Hub, choose the server, and log in with a narrowly scoped credential. Coolify runs the login for the server user it uses for Docker. Check the login in the same interface before deploying.

If your installed Coolify version uses server-side SSH configuration instead, connect as the exact configured server user and use standard input so the token does not appear in the command line:

printf '%s' "$REGISTRY_TOKEN" | \
  docker login docker.io \
  --username REGISTRY_USER \
  --password-stdin

Never put the token in a Dockerfile, Compose file, Git repository, build argument, or public environment example. Confirm that the resulting Docker configuration belongs to the actual Coolify user. Running sudo docker login may write credentials under root while an unprivileged Coolify SSH user continues pulling anonymously.

5. Reduce unnecessary pulls and retries

Authentication raises the documented allowance for a free personal account, but it does not excuse wasteful automation. Remove the behaviour that made normal deployment traffic bursty:

• disable duplicate webhook deliveries or overlapping scheduled deploys;
• cancel redundant queued deployments rather than letting each pull the same base;
• use a lockfile and intentional base-image versions instead of floating tags;
• retain a useful BuildKit layer cache on the build server;
• build once in CI and publish once when many deployment servers need the same artifact;
• use exponential backoff with a strict attempt ceiling for transient registry failures;
• investigate a bare abuse-limit 429 before sending any more requests.

Do not solve this by deploying an unreviewed public mirror, disabling TLS verification, or copying registry credentials into every application container. A mirror becomes part of your software-supply chain and needs access control, retention, integrity, capacity, and backup planning.

6. Consider another registry for images you own

If your own application image is already built in GitHub Actions, publishing it to GHCR can separate that artifact from Docker Hub base-image traffic. Private GHCR images still require package permission and a read-capable credential on every deployment server. Public GHCR images can be pulled anonymously, while private packages should use the least privilege that can read the package.

This does not automatically eliminate Docker Hub pulls during a source build. A Dockerfile beginning with a Docker Hub base image still fetches that base on the build machine unless it is already cached or you deliberately maintain a trusted copy. Record provenance and update policy if you mirror a base image; an old unpatched copy is not a resilience win.

7. Retry once and prove the deployed digest

Once authentication and the retry source are corrected, trigger one Coolify deployment. Follow its opaque deployment ID until a terminal status. Then verify more than a green badge:

1. Confirm the deployment log pulled the intended repository and version or digest.
2. Inspect the running container’s immutable image ID and repository digest.
3. Match the release to the intended source commit or CI artifact.
4. Verify container health and application logs.
5. Fetch a unique changed heading, response, or release marker from the public domain.
6. Check critical API and asset routes rather than accepting only HTTP 200 at /.
7. Confirm another automatic deployment does not immediately repeat the pull storm.

docker inspect APP_CONTAINER \
  --format 'image={{.Config.Image}} id={{.Image}} started={{.State.StartedAt}}'

docker image inspect EXPECTED_IMAGE_REFERENCE \
  --format '{{json .RepoDigests}}'

Prefer a version tag or immutable digest for production images. Coolify documents that restarting a Docker Image application pulls its saved image reference again; if that reference is a mutable tag, a restart can change application content even without a source change.

Repairs to avoid

• Clicking Deploy repeatedly: it consumes more queue and registry work without changing the failed identity.
• Using someone else’s credentials: registry access must be owned, scoped, and revocable.
• Putting tokens in app environment output: registry login belongs to the server’s Docker client context.
• Deleting all Docker data: a cache purge increases pulls and can remove rollback images or unrelated state.
• Switching to an arbitrary mirror: availability does not establish authenticity or maintenance.
• Treating every 429 alike: pull allowance and abuse protection need different responses.
• Reporting success after a queued response: wait for terminal deployment state and verify the live artifact.

Compact recovery order

1. Record the exact deployment, server, image reference, operation, and full 429 message.
2. Stop duplicate deployments and automated retry loops.
3. Identify build server, deployment server, Swarm nodes, operating-system user, and shared egress boundary.
4. Reproduce one exact pull from the relevant host and user.
5. Authenticate that server user through Coolify’s registry configuration with least privilege.
6. Remove the cause of excessive pulls and preserve useful caches.
7. Retry once, poll to terminal state, and verify the running image digest plus unique live content.
8. Monitor the next ordinary deployment to prove the fix persists.

Authoritative references: Docker’s official Hub usage and limits page lists the current authenticated and anonymous pull allowances and explains the separate abuse limit; its troubleshooting guide distinguishes the two 429 messages. Coolify’s Docker registries guide explains server-scoped authentication, separate build/deployment servers, and Docker credential storage, while its Docker Image guide covers tags, digests, pulls, and restart behaviour. Check current provider terms and your installed Coolify version before applying commands.