Testcontainers slow first image pull timing out tests in CI

By Kaveh Alemi·Latchkey

On a fresh runner the first pull downloads every image layer, which can take minutes for large images. If the pull time counts against the container wait strategy, a healthy container can be reported as timing out.

What this error means

The first test that uses a given image is far slower than later ones, and sometimes fails a readiness timeout, while re-runs on a warm cache pass quickly.

Pulling docker image: X. Please be patient; this may take some time but only needs to be done once.
(Then: Timed out waiting for container to be ready - the pull ate the startup budget.)

Common causes

Fresh runners have a cold image cache

Every ephemeral runner starts with no images, so the first pull downloads full layers over the network.

Pull time counts toward container startup budget

If readiness timing includes the pull, a large cold image can exhaust the wait-strategy window.

How to fix it

Pre-pull images before the test step

Pull required images explicitly so the wait strategy times only startup, not the download.

- run: docker pull postgres:16 && docker pull localstack/localstack:3
- run: mvn test

Cache or mirror images across runs

Use a registry mirror or a warm image cache so subsequent runs skip most of the download.

How to prevent it

• Pre-pull heavy images so startup timeouts exclude download time.
• Use a registry mirror or warm cache for frequently used images.
• Prefer slim images to shorten cold pulls.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation