{"record":{"id":"ddffdae2ad32db7f","repo":"testcontainers/testcontainers-java","slug":"retrying-pull-for-image-s-remaining","errorCode":null,"errorMessage":"Retrying pull for image: {} ({}s remaining)","messagePattern":"Retrying pull for image: (.+?) \\((.+?)s remaining\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/images/RemoteDockerImage.java","lineNumber":149,"sourceCode":"    }\n\n    private Callable<Boolean> tryImagePullCommand(\n        PullImageCmd pullImageCmd,\n        Logger logger,\n        AtomicReference<String> dockerImageName,\n        DockerImageName imageName,\n        AtomicReference<Exception> lastFailure,\n        Instant lastRetryAllowed\n    ) {\n        return () -> {\n            try {\n                pullImage(pullImageCmd, logger);\n                dockerImageName.set(imageName.asCanonicalNameString());\n                return true;\n            } catch (InterruptedException | InternalServerErrorException e) {\n                // these classes of exception often relate to timeout/connection errors so should be retried\n                lastFailure.set(e);\n                logger.warn(\n                    \"Retrying pull for image: {} ({}s remaining)\",\n                    imageName,\n                    Duration.between(Instant.now(), lastRetryAllowed).getSeconds()\n                );\n                return false;\n            }\n        };\n    }\n\n    private TimeLimitedLoggedPullImageResultCallback pullImage(PullImageCmd pullImageCmd, Logger logger)\n        throws InterruptedException {\n        try {\n            return pullImageCmd.exec(new TimeLimitedLoggedPullImageResultCallback(logger)).awaitCompletion();\n        } catch (DockerClientException | NotFoundException e) {\n            // Try to fallback to x86\n            return pullImageCmd\n                .withPlatform(\"linux/amd64\")\n                .exec(new TimeLimitedLoggedPullImageResultCallback(logger))","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/images/RemoteDockerImage.java#L131-L167","documentation":"RemoteDockerImage retries pulling an image for up to a time budget when the pull fails with InterruptedException or InternalServerErrorException (often Docker daemon timeouts or connection issues). This warning logs each retry attempt and how many seconds remain before retries stop.","triggerScenarios":"tryImagePullCommand catches InternalServerErrorException or InterruptedException from pullImage during RemoteDockerImage.resolve()/get(); repeated until the lastRetryAllowed deadline.","commonSituations":"Slow or flaky Docker Hub / registry connection; Docker daemon under heavy load returning 500s; corporate proxy throttling; large images timing out mid-pull.","solutions":["Pre-pull the image with `docker pull <image>` before running tests","Increase the retry budget via the testcontainers pull.timeout / retry settings (RemoteDockerImage withTimeLimit)","Use a faster/closer registry mirror and check daemon/network stability"],"exampleFix":"// before\nnew RemoteDockerImage(DockerImageName.parse(\"postgres:16\")).get();\n// after: longer budget and pre-pull\nnew RemoteDockerImage(DockerImageName.parse(\"postgres:16\"))\n    .withTimeLimit(Duration.ofMinutes(10))\n    .get();","handlingStrategy":"retry","validationCode":"// pre-check image presence to avoid pulling\nboolean present = new RemoteDockerImage(imageName).isPresent();\nif (!present) { /* pre-pull with docker CLI or extend time budget */ }","typeGuard":null,"tryCatchPattern":"try {\n    String id = new RemoteDockerImage(imageName).get();\n} catch (Exception e) {\n    // retries already exhausted; check daemon health and registry connectivity\n    throw new IllegalStateException(\"Image pull failed after retries: \" + imageName, e);\n}","preventionTips":["Pre-pull images in CI setup step","Increase RemoteDockerImage time budget for large images","Use a local registry mirror and monitor daemon health"],"tags":["testcontainers","docker-pull","retry","network"],"backgroundTag":"request-timeout","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}