{"record":{"id":"9dc32e1063c13e94","repo":"testcontainers/testcontainers-java","slug":"exception-while-pulling-images-using-local-images-if-9dc32e","errorCode":null,"errorMessage":"Exception while pulling images, using local images if available","messagePattern":"Exception while pulling images, using local images if available","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/containers/DockerComposeContainer.java","lineNumber":180,"sourceCode":"                ComposeDelegate.ComposeVersion.V1,\n                composeFiles,\n                identifier,\n                COMPOSE_EXECUTABLE,\n                DockerImageName.parse(\"docker/compose:1.29.2\")\n            );\n        this.project = this.composeDelegate.getProject();\n        this.localCompose = true;\n    }\n\n    @Override\n    public void start() {\n        synchronized (MUTEX) {\n            this.composeDelegate.registerContainersForShutdown();\n            if (pull) {\n                try {\n                    this.composeDelegate.pullImages();\n                } catch (ContainerLaunchException e) {\n                    log.warn(\"Exception while pulling images, using local images if available\", e);\n                }\n            }\n            this.composeDelegate.createServices(\n                    this.localCompose,\n                    this.build,\n                    this.options,\n                    this.services,\n                    this.scalingPreferences,\n                    this.env,\n                    this.filesInDirectory\n                );\n            this.composeDelegate.startAmbassadorContainer();\n            this.composeDelegate.waitUntilServiceStarted(this.tailChildContainers);\n        }\n    }\n\n    @VisibleForTesting\n    List<Container> listChildContainers() {","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/DockerComposeContainer.java#L162-L198","documentation":"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.","triggerScenarios":"pull flag enabled (default) and composeDelegate.pullImages() throws during start(); missing registry credentials, no network access, or image not pushed to any registry.","commonSituations":"Using locally built images never pushed anywhere; CI without internet or behind a proxy; Docker Hub rate limits; private registries lacking docker login.","solutions":["Pre-pull or pre-build all compose images before running tests","Skip pulling with new DockerComposeContainer(file).withPull(false) when images are local","Authenticate to the registry (docker login) before the test run","Ignore the warning if local images are intentionally used (this is what usesLocalImageEvenWhenPullFails tests)"],"exampleFix":"// before\nDockerComposeContainer compose = new DockerComposeContainer(new File(\"docker-compose.yml\"));\n// after\nDockerComposeContainer compose = new DockerComposeContainer(new File(\"docker-compose.yml\")).withPull(false);","handlingStrategy":"fallback","validationCode":"// Verify all compose images are available locally when pull=false\nfor (String img : declaredComposeImages(\"docker-compose.yml\")) {\n    if (!imageExistsLocally(img)) {\n        dockerClient.pullImageCmd(img).exec(new PullImageResultCallback()).awaitSuccess();\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    compose.start();\n} catch (ContainerLaunchException e) {\n    log.error(\"Compose failed after pull-fallback; check images exist locally\", e);\n    throw e;\n}","preventionTips":["Pre-build or pre-pull compose images before tests","Set withPull(false) only when images are guaranteed local","Authenticate to private registries before the test run"],"tags":["docker-compose","image-pull","registry","fallback"],"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"}