Testcontainers "Previously pulled image ... not available" in CI

Testcontainers expected an image to already be present locally but the daemon no longer has it, so it tries to pull again. When that re-pull cannot complete (network, auth, or a pruned cache), startup fails.

What this error means

Setup logs "Previously pulled image, but not available locally" and then fails if the re-pull errors, typically after a cache prune or on a runner where the image was evicted.

Previously pulled image, but not available locally: X. Pulling image: X
Caused by: image pull failed

Common causes

The local image was pruned or evicted

A cleanup step or fresh runner removed the cached image, so the reference resolves but the layers are gone.

The re-pull cannot reach the registry

When the automatic re-pull hits a rate limit, auth error, or network failure, the missing image cannot be restored.

How to fix it

Ensure the image is pulled reliably before tests

Pre-pull required images in a setup step with authentication so they are present when tests start.

- run: docker pull postgres:16
- run: mvn test

Do not prune images the test suite needs

Keep test images out of aggressive cleanup steps, or re-pull them after any prune.

How to prevent it

• Pre-pull test images in a dedicated authenticated step.
• Avoid pruning images that later test steps depend on.
• Pin image tags so the pull target is stable.

Related guides