testcontainers/testcontainers-java · warning

Exception while pulling images, using local images if…

Error message

Exception while pulling images, using local images if available

What it means

DockerComposeContainer.start() tries to pull all images declared in the compose file before starting services. A ContainerLaunchException from pulling is caught and logged at WARN; startup proceeds assuming local images exist. The actual container creation step will fail later if the images truly cannot be obtained.

Solutions

1. Pre-pull or pre-build all compose images before running tests
2. Skip pulling with new DockerComposeContainer(file).withPull(false) when images are local
3. Authenticate to the registry (docker login) before the test run
4. Ignore the warning if local images are intentionally used (this is what usesLocalImageEvenWhenPullFails tests)

Example fix

// before
DockerComposeContainer compose = new DockerComposeContainer(new File("docker-compose.yml"));
// after
DockerComposeContainer compose = new DockerComposeContainer(new File("docker-compose.yml")).withPull(false);

// Verify all compose images are available locally when pull=false
for (String img : declaredComposeImages("docker-compose.yml")) {
    if (!imageExistsLocally(img)) {
        dockerClient.pullImageCmd(img).exec(new PullImageResultCallback()).awaitSuccess();
    }
}

try {
    compose.start();
} catch (ContainerLaunchException e) {
    log.error("Compose failed after pull-fallback; check images exist locally", e);
    throw e;
}

When it happens

Trigger: pull flag enabled (default) and composeDelegate.pullImages() throws during start(); missing registry credentials, no network access, or image not pushed to any registry.

Common situations: Using locally built images never pushed anywhere; CI without internet or behind a proxy; Docker Hub rate limits; private registries lacking docker login.

Related errors

• Exception while pulling images, using local images if…
• Unable to pre-fetch an image
• Failed to pull image
• Unable to pre-fetch an image
• Services named do not exist, but wait conditions have been…

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/9dc32e1063c13e94. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/DockerComposeContainer.java:180

                ComposeDelegate.ComposeVersion.V1,
                composeFiles,
                identifier,
                COMPOSE_EXECUTABLE,
                DockerImageName.parse("docker/compose:1.29.2")
            );
        this.project = this.composeDelegate.getProject();
        this.localCompose = true;
    }

    @Override
    public void start() {
        synchronized (MUTEX) {
            this.composeDelegate.registerContainersForShutdown();
            if (pull) {
                try {
                    this.composeDelegate.pullImages();
                } catch (ContainerLaunchException e) {
                    log.warn("Exception while pulling images, using local images if available", e);
                }
            }
            this.composeDelegate.createServices(
                    this.localCompose,
                    this.build,
                    this.options,
                    this.services,
                    this.scalingPreferences,
                    this.env,
                    this.filesInDirectory
                );
            this.composeDelegate.startAmbassadorContainer();
            this.composeDelegate.waitUntilServiceStarted(this.tailChildContainers);
        }
    }

    @VisibleForTesting
    List<Container> listChildContainers() {

View on GitHub (pinned to 8e549514e3)