{"record":{"id":"9e1c3145dccd7aea","repo":"testcontainers/testcontainers-java","slug":"exception-while-pulling-images-using-local-images-if","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/ComposeContainer.java","lineNumber":167,"sourceCode":"    }\n\n    /**\n     * Use the new constructor {@link #ComposeContainer(DockerImageName image, String identifier, List composeFiles)}\n     */\n    public ComposeContainer(String identifier, List<File> composeFiles) {\n        this(DEFAULT_IMAGE_NAME, identifier, composeFiles);\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":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/ComposeContainer.java#L149-L185","documentation":"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.","triggerScenarios":"Composable delegate pullImages() throws ContainerLaunchException during start() when the pull flag is enabled (default); registry auth missing, offline environment, or nonexistent image tags.","commonSituations":"CI environments with no Docker Hub access or rate limiting; images built locally that were never pushed; private registries without configured credentials.","solutions":["Pre-build or docker pull the compose images before running the test","Set pull=false via new ComposeContainer(...).withPull(false) to skip remote pulls for local images","Configure registry credentials (docker login / Testcontainers registry auth) so the pull succeeds","If pull failure is expected, ignore the warning — local images will be used"],"exampleFix":"// before\nComposeContainer compose = new ComposeContainer(new File(\"docker-compose.yml\"));\n// after (use local images)\nComposeContainer compose = new ComposeContainer(new File(\"docker-compose.yml\")).withPull(false);","handlingStrategy":"fallback","validationCode":"// Pre-check images before start()\nfor (String img : List.of(\"postgres:16\", \"redis:7\")) {\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    // pull already warned; a real failure surfaces here during createServices\n    log.error(\"Compose startup failed even with local fallback\", e);\n    throw e;\n}","preventionTips":["Pre-pull images in CI before running compose-based tests","Use withPull(false) for locally built images","Configure registry credentials in the test environment"],"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"}