testcontainers/testcontainers-java · error · ContainerLaunchException

Timed out waiting for container to execute

Error message

Timed out waiting for container to execute `%s` successfully.

What it means

ShellStrategy waits by repeatedly executing /bin/sh -c <command> inside the container until it exits with code 0. If the command still returns a non-zero exit code when the startup timeout expires, a TimeoutException is wrapped in this ContainerLaunchException naming the command.

Solutions

1. Run the command manually: container.execInContainer("/bin/sh","-c",cmd) and inspect output/exit code
2. Fix the probe command (correct host, credentials, and an available tool like nc/curl)
3. Increase the timeout: strategy.withStartupTimeout(Duration.ofMinutes(2))
4. Consider a HttpWaitStrategy/LogMessageWaitStrategy if a probe command is awkward

Example fix

// before
new ShellStrategy().withCommand("curl -f http://localhost:8080/health").withStartupTimeout(Duration.ofSeconds(20));
// after
new ShellStrategy().withCommand("wget -qO- http://localhost:8080/health || exit 1").withStartupTimeout(Duration.ofMinutes(2));

// Probe the command once before relying on it for the wait strategy
ExecResult r = container.execInContainer("/bin/sh", "-c", probeCommand);
if (r.getExitCode() != 0) {
    throw new IllegalStateException("Probe failed (exit " + r.getExitCode() + "): " + r.getStderr());
}

try {
    container.waitingFor(new ShellStrategy().withCommand(probeCommand)).start();
} catch (ContainerLaunchException e) {
    if (e.getMessage().startsWith("Timed out waiting for container to execute")) {
        System.err.println(container.execInContainer("/bin/sh", "-c", probeCommand).getStderr());
    }
    throw e;
}

When it happens

Trigger: Container startup configured with new ShellStrategy().withCommand("psql -h host -U user ...") (often inside .waitingFor(...)) while the probe command keeps failing — target service not up, wrong credentials/host, or the command itself is buggy.

Common situations: Port-check one-liners (e.g. 'wget --spider ...') failing because the inner service is not ready or wget/curl isn't installed; wrong DB user/password in the probe; timeout too short for the dependent service to boot.

Understand the failure class

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

Related errors

• Timed out waiting for URL to be accessible
• Timed out waiting for log output matching
• Changing startup timeout is not supported with mode
• Timed out waiting for container to become healthy
• Timed out waiting for container port to open ( host ports: …

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/wait/strategy/ShellStrategy.java:27

public class ShellStrategy extends AbstractWaitStrategy {

    private String command;

    public ShellStrategy withCommand(String command) {
        this.command = command;
        return this;
    }

    @Override
    protected void waitUntilReady() {
        try {
            Unreliables.retryUntilTrue(
                (int) startupTimeout.getSeconds(),
                TimeUnit.SECONDS,
                () -> waitStrategyTarget.execInContainer("/bin/sh", "-c", this.command).getExitCode() == 0
            );
        } catch (TimeoutException e) {
            throw new ContainerLaunchException(
                "Timed out waiting for container to execute `" + this.command + "` successfully."
            );
        }
    }
}

View on GitHub (pinned to 8e549514e3)