{"record":{"id":"b3534a5b3aa53b33","repo":"testcontainers/testcontainers-java","slug":"unable-to-pre-fetch-an-image-depended-upon-by-docker-compose","errorCode":null,"errorMessage":"Unable to pre-fetch an image ({}) depended upon by Docker Compose build - startup will continue but may fail. Exception message was: {}","messagePattern":"Unable to pre-fetch an image \\((.+?)\\) depended upon by Docker Compose build - startup will continue but may fail\\. Exception message was: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/containers/ComposeDelegate.java","lineNumber":113,"sourceCode":"        this.defaultImageName = defaultImageName;\n    }\n\n    void pullImages() {\n        // Pull images using our docker client rather than compose itself,\n        // (a) as a workaround for https://github.com/docker/compose/issues/5854, which prevents authenticated image pulls being possible when credential helpers are in use\n        // (b) so that credential helper-based auth still works when compose is running from within a container\n        this.dockerComposeFiles.getDependencyImages()\n            .forEach(imageName -> {\n                try {\n                    log.info(\n                        \"Preemptively checking local images for '{}', referenced via a compose file or transitive Dockerfile. If not available, it will be pulled.\",\n                        imageName\n                    );\n                    new RemoteDockerImage(DockerImageName.parse(imageName))\n                        .withImageNameSubstitutor(ImageNameSubstitutor.noop())\n                        .get();\n                } catch (Exception e) {\n                    log.warn(\n                        \"Unable to pre-fetch an image ({}) depended upon by Docker Compose build - startup will continue but may fail. Exception message was: {}\",\n                        imageName,\n                        e.getMessage()\n                    );\n                }\n            });\n    }\n\n    void createServices(\n        boolean localCompose,\n        boolean build,\n        final Set<String> options,\n        final List<String> services,\n        final Map<String, Integer> scalingPreferences,\n        Map<String, String> env,\n        List<String> fileCopyInclusions\n    ) {\n        // services that have been explicitly requested to be started. If empty, all services should be started.","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/ComposeDelegate.java#L95-L131","documentation":"ComposeDelegate.pullImages() pre-fetches images referenced by a locally built compose file so the build has them available. Each pre-fetch runs in parallel and any Exception from RemoteDockerImage.get() is swallowed with a WARN; startup continues but the later compose build may fail if the image is genuinely unavailable.","triggerScenarios":"A Docker Compose build references an image (from the 'image:' key of a service with 'build:') that cannot be pulled — registry unreachable, tag missing, or credentials absent.","commonSituations":"Building custom compose images whose base image tag was removed from Docker Hub; offline CI; private base images without auth.","solutions":["Pre-pull the base image manually (docker pull <imageName>) before the test runs","Pin base image tags in the compose Dockerfile to tags that exist in the registry","Configure Docker registry credentials for the private base image","Verify network access to the registry from the test environment"],"exampleFix":"// before\nFROM some-private-registry/base:latest\n// after (pin an existing tag and pre-pull)\nFROM some-private-registry/base:1.2.3  // ensure: docker pull some-private-registry/base:1.2.3","handlingStrategy":"fallback","validationCode":"// Ensure the base image referenced by a compose build exists before the test\nString base = \"myregistry/base:1.2.3\";\nif (!imageExistsLocally(base)) {\n    dockerClient.pullImageCmd(base).exec(new PullImageResultCallback()).awaitSuccess();\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin base image tags that exist in the registry","Pre-pull base images before running compose builds","Verify registry connectivity and auth in CI"],"tags":["docker-compose","image-pull","registry","prefetch"],"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"}