testcontainers/testcontainers-java · warning

Unable to pre-fetch an image

Error message

Unable to pre-fetch an image ({}) depended upon by Dockerfile - image build will continue but may fail. Exception message was: {}

What it means

ImageFromDockerfile pre-pulls images referenced in FROM lines of the Dockerfile so the daemon-side build doesn't hit network problems. If any pre-pull fails, this warning logs the image and exception message, and the build continues (the daemon will attempt the pull itself during build).

Solutions

Run `docker pull <base-image>` manually to see the underlying error and fix credentials/tag
Configure registry auth (docker config or Testcontainers env) so private base images can be fetched
Correct the FROM reference in the Dockerfile or use a mirror

Example fix

// before: Dockerfile FROM mycompany/private:1.2 failing pre-pull
// after: log in first
$ docker login registry.mycompany.com
// and verify
$ docker pull mycompany/private:1.2

Defensive patterns

Strategy: validation

Validate before calling

for (String img : fromImages) {
    Process p = new ProcessBuilder("docker", "pull", img).inheritIO().start();
    if (p.waitFor() != 0) throw new IllegalStateException("Cannot pull base image: " + img);
}

Try / catch

try {
    new RemoteDockerImage(DockerImageName.parse(baseImage)).get();
} catch (Exception e) {
    logger.warn("pre-pull of {} failed: {}", baseImage, e.getMessage());
    // proceed — daemon will pull during build, or abort intentionally
}

Prevention

docker login to private registries before tests
Pin FROM tags that exist
Verify registry reachability from CI network

When it happens

Trigger: prePullDependencyImages() calls new RemoteDockerImage(...).get() for each image parsed from the Dockerfile and any exception is caught and logged during resolve().

Common situations: Private base image without registry credentials configured; typo'd or nonexistent FROM tag; registry unreachable from the test environment; rate limits from Docker Hub.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/images/builder/ImageFromDockerfile.java:204

        this.buildArgs.forEach(buildImageCmd::withBuildArg);
        this.target.ifPresent(buildImageCmd::withTarget);
        this.buildImageCmdModifiers.forEach(hook -> hook.accept(buildImageCmd));
    }

    private void prePullDependencyImages(Set<String> imagesToPull) {
        imagesToPull.forEach(imageName -> {
            String resolvedImageName = applyBuildArgsToImageName(imageName);
            try {
                log.info(
                    "Pre-emptively checking local images for '{}', referenced via a Dockerfile. If not available, it will be pulled.",
                    resolvedImageName
                );
                new RemoteDockerImage(DockerImageName.parse(resolvedImageName))
                    .withImageNameSubstitutor(ImageNameSubstitutor.noop())
                    .get();
            } catch (Exception e) {
                log.warn(
                    "Unable to pre-fetch an image ({}) depended upon by Dockerfile - image build will continue but may fail. Exception message was: {}",
                    resolvedImageName,
                    e.getMessage()
                );
            }
        });
    }

    /**
     * See {@code filterForEnvironmentVars()} in {@link com.github.dockerjava.core.dockerfile.DockerfileStatement}.
     */
    private String applyBuildArgsToImageName(String imageName) {
        for (Map.Entry<String, String> entry : buildArgs.entrySet()) {
            String value = Matcher.quoteReplacement(entry.getValue());
            // handle: $VARIABLE case
            imageName = imageName.replace("$" + entry.getKey(), value);
            // handle ${VARIABLE} case
            imageName = imageName.replace("${" + entry.getKey() + "}", value);

View on GitHub (pinned to 8e549514e3)