What causes "Timed out waiting for container to become healthy" in testcontainers/testcontainers-java?

testcontainers/testcontainers-java · error · ContainerLaunchException

Timed out waiting for container to become healthy

Error message

Timed out waiting for container to become healthy

What it means

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.

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).

Example fix

// before
.waitingFor(new DockerHealthcheckWaitStrategy());
// after
.waitingFor(new DockerHealthcheckWaitStrategy().withStartupTimeout(Duration.ofMinutes(3)));

Defensive patterns

Strategy: try-catch

Try / catch

try { container.waitingFor(new DockerHealthcheckWaitStrategy().withStartupTimeout(Duration.ofMinutes(3))); } catch (ContainerLaunchException e) { log.error("healthcheck never passed; logs: {}", container.getLogs()); throw e; }

Prevention

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.

When it happens

Trigger: 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.

Common situations: Slow service initialization (DB migrations) exceeding the default timeout, HEALTHCHECK interval too long, image without HEALTHCHECK being used with this strategy by mistake.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/a02d52cdebe51655. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/wait/strategy/DockerHealthcheckWaitStrategy.java:25

import java.util.concurrent.TimeUnit;

/**
 * Wait strategy leveraging Docker's built-in healthcheck mechanism.
 *
 * @see <a href="https://docs.docker.com/engine/reference/builder/#healthcheck">https://docs.docker.com/engine/reference/builder/#healthcheck</a>
 */
public class DockerHealthcheckWaitStrategy extends AbstractWaitStrategy {

    @Override
    protected void waitUntilReady() {
        try {
            Unreliables.retryUntilTrue(
                (int) startupTimeout.getSeconds(),
                TimeUnit.SECONDS,
                waitStrategyTarget::isHealthy
            );
        } catch (TimeoutException e) {
            throw new ContainerLaunchException("Timed out waiting for container to become healthy");
        }
    }
}

View on GitHub (pinned to 8e549514e3)