{"record":{"id":"c46b908983a94c34","repo":"testcontainers/testcontainers-java","slug":"unable-to-pre-fetch-an-image-depended-upon-by-dockerfile","errorCode":null,"errorMessage":"Unable to pre-fetch an image ({}) depended upon by Dockerfile - image build will continue but may fail. Exception message was: {}","messagePattern":"Unable to pre-fetch an image \\((.+?)\\) depended upon by Dockerfile - image build will continue but may fail\\. Exception message was: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/images/builder/ImageFromDockerfile.java","lineNumber":204,"sourceCode":"\n        this.buildArgs.forEach(buildImageCmd::withBuildArg);\n        this.target.ifPresent(buildImageCmd::withTarget);\n        this.buildImageCmdModifiers.forEach(hook -> hook.accept(buildImageCmd));\n    }\n\n    private void prePullDependencyImages(Set<String> imagesToPull) {\n        imagesToPull.forEach(imageName -> {\n            String resolvedImageName = applyBuildArgsToImageName(imageName);\n            try {\n                log.info(\n                    \"Pre-emptively checking local images for '{}', referenced via a Dockerfile. If not available, it will be pulled.\",\n                    resolvedImageName\n                );\n                new RemoteDockerImage(DockerImageName.parse(resolvedImageName))\n                    .withImageNameSubstitutor(ImageNameSubstitutor.noop())\n                    .get();\n            } catch (Exception e) {\n                log.warn(\n                    \"Unable to pre-fetch an image ({}) depended upon by Dockerfile - image build will continue but may fail. Exception message was: {}\",\n                    resolvedImageName,\n                    e.getMessage()\n                );\n            }\n        });\n    }\n\n    /**\n     * See {@code filterForEnvironmentVars()} in {@link com.github.dockerjava.core.dockerfile.DockerfileStatement}.\n     */\n    private String applyBuildArgsToImageName(String imageName) {\n        for (Map.Entry<String, String> entry : buildArgs.entrySet()) {\n            String value = Matcher.quoteReplacement(entry.getValue());\n            // handle: $VARIABLE case\n            imageName = imageName.replace(\"$\" + entry.getKey(), value);\n            // handle ${VARIABLE} case\n            imageName = imageName.replace(\"${\" + entry.getKey() + \"}\", value);","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/images/builder/ImageFromDockerfile.java#L186-L222","documentation":"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).","triggerScenarios":"prePullDependencyImages() calls new RemoteDockerImage(...).get() for each image parsed from the Dockerfile and any exception is caught and logged during resolve().","commonSituations":"Private base image without registry credentials configured; typo'd or nonexistent FROM tag; registry unreachable from the test environment; rate limits from Docker Hub.","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"],"exampleFix":"// before: Dockerfile FROM mycompany/private:1.2 failing pre-pull\n// after: log in first\n$ docker login registry.mycompany.com\n// and verify\n$ docker pull mycompany/private:1.2","handlingStrategy":"validation","validationCode":"for (String img : fromImages) {\n    Process p = new ProcessBuilder(\"docker\", \"pull\", img).inheritIO().start();\n    if (p.waitFor() != 0) throw new IllegalStateException(\"Cannot pull base image: \" + img);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new RemoteDockerImage(DockerImageName.parse(baseImage)).get();\n} catch (Exception e) {\n    logger.warn(\"pre-pull of {} failed: {}\", baseImage, e.getMessage());\n    // proceed — daemon will pull during build, or abort intentionally\n}","preventionTips":["docker login to private registries before tests","Pin FROM tags that exist","Verify registry reachability from CI network"],"tags":["testcontainers","docker-build","image-pull","registry"],"backgroundTag":"image-pull-failed","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}