{"record":{"id":"a02d52cdebe51655","repo":"testcontainers/testcontainers-java","slug":"timed-out-waiting-for-container-to-become-healthy","errorCode":null,"errorMessage":"Timed out waiting for container to become healthy","messagePattern":"Timed out waiting for container to become healthy","errorType":"exception","errorClass":"ContainerLaunchException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/wait/strategy/DockerHealthcheckWaitStrategy.java","lineNumber":25,"sourceCode":"import java.util.concurrent.TimeUnit;\n\n/**\n * Wait strategy leveraging Docker's built-in healthcheck mechanism.\n *\n * @see <a href=\"https://docs.docker.com/engine/reference/builder/#healthcheck\">https://docs.docker.com/engine/reference/builder/#healthcheck</a>\n */\npublic class DockerHealthcheckWaitStrategy extends AbstractWaitStrategy {\n\n    @Override\n    protected void waitUntilReady() {\n        try {\n            Unreliables.retryUntilTrue(\n                (int) startupTimeout.getSeconds(),\n                TimeUnit.SECONDS,\n                waitStrategyTarget::isHealthy\n            );\n        } catch (TimeoutException e) {\n            throw new ContainerLaunchException(\"Timed out waiting for container to become healthy\");\n        }\n    }\n}\n","sourceCodeStart":7,"sourceCodeEnd":29,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/wait/strategy/DockerHealthcheckWaitStrategy.java#L7-L29","documentation":"DockerHealthcheckWaitStrategy polls the container's Docker-defined HEALTHCHECK status via Unreliables.retryUntilTrue until startupTimeout elapses. If the container never reports healthy, a ContainerLaunchException with this message is thrown. Note the cause (TimeoutException) is dropped, so check container logs to diagnose.","triggerScenarios":"container.waitingFor(new DockerHealthcheckWaitStrategy()) where the image's HEALTHCHECK keeps failing or starting past the startup timeout; or the image has no HEALTHCHECK so isHealthy never turns true.","commonSituations":"Slow service initialization (DB migrations) exceeding the default timeout, HEALTHCHECK interval too long, image without HEALTHCHECK being used with this strategy by mistake.","solutions":["Extend the timeout: `new DockerHealthcheckWaitStrategy().withStartupTimeout(Duration.ofMinutes(5))`.","Inspect `container.getLogs()` and `docker inspect` health output for why the check fails.","Confirm the image actually defines a HEALTHCHECK; otherwise use another strategy.","Fix the underlying service so its healthcheck passes (deps reachable, config correct)."],"exampleFix":"// before\n.waitingFor(new DockerHealthcheckWaitStrategy());\n// after\n.waitingFor(new DockerHealthcheckWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)));","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { container.waitingFor(new DockerHealthcheckWaitStrategy().withStartupTimeout(Duration.ofMinutes(3))); } catch (ContainerLaunchException e) { log.error(\"healthcheck never passed; logs: {}\", container.getLogs()); throw e; }","preventionTips":["Only use this strategy on images that define a HEALTHCHECK.","Tune HEALTHCHECK interval/retries in the Dockerfile for slow apps.","Always capture container logs on wait failure for diagnosis."],"tags":["healthcheck","wait-strategy","timeout"],"backgroundTag":"request-timeout","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"}