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

ComposeContainer.start() attempts to pull all compose-defined images before creating services. If pulling fails with a ContainerLaunchException (e.g. the registry is unreachable or an image doesn't exist remotely), the exception is caught and logged as a warning, and startup continues assuming the images exist locally. Only a later container creation failure will surface as a hard error.

Solutions

1. Pre-build or docker pull the compose images before running the test
2. Set pull=false via new ComposeContainer(...).withPull(false) to skip remote pulls for local images
3. Configure registry credentials (docker login / Testcontainers registry auth) so the pull succeeds
4. If pull failure is expected, ignore the warning — local images will be used

Example fix

// before
ComposeContainer compose = new ComposeContainer(new File("docker-compose.yml"));
// after (use local images)
ComposeContainer compose = new ComposeContainer(new File("docker-compose.yml")).withPull(false);

// Pre-check images before start()
for (String img : List.of("postgres:16", "redis:7")) {
    if (!imageExistsLocally(img)) {
        dockerClient.pullImageCmd(img).exec(new PullImageResultCallback()).awaitSuccess();
    }
}

try {
    compose.start();
} catch (ContainerLaunchException e) {
    // pull already warned; a real failure surfaces here during createServices
    log.error("Compose startup failed even with local fallback", e);
    throw e;
}

When it happens

Trigger: Composable delegate pullImages() throws ContainerLaunchException during start() when the pull flag is enabled (default); registry auth missing, offline environment, or nonexistent image tags.

Common situations: CI environments with no Docker Hub access or rate limiting; images built locally that were never pushed; private registries without configured credentials.

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/9e1c3145dccd7aea. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ComposeContainer.java:167

    }

    /**
     * Use the new constructor {@link #ComposeContainer(DockerImageName image, String identifier, List composeFiles)}
     */
    public ComposeContainer(String identifier, List<File> composeFiles) {
        this(DEFAULT_IMAGE_NAME, identifier, composeFiles);
        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)