testcontainers/testcontainers-java · error · org.testcontainers.containers.ContainerLaunchException

Timed out waiting for Cassandra to be accessible for query…

Error message

Timed out waiting for Cassandra to be accessible for query execution

What it means

CassandraQueryWaitStrategy waits until the Cassandra container accepts CQL queries before the container is considered ready. If no successful query executes within the wait strategy timeout (default ~60s), it wraps the TimeoutException in a ContainerLaunchException with TIMEOUT_ERROR. This is Testcontainers' way of signaling the node never became queryable.

Solutions

1. Increase the wait strategy timeout: new CassandraQueryWaitStrategy().withStartupTimeout(Duration.ofMinutes(5)) and set via container.waitingFor(...)
2. Check container logs (container.getLogs()) for Cassandra startup/crash errors
3. Use a lighter/supported Cassandra image tag (e.g. cassandra:4.x) and adequate memory (Cassandra needs several GB)
4. Ensure the host has enough free memory/CPU; Cassandra JVM heap defaults can OOM in constrained environments

Example fix

// before
CassandraContainer c = new CassandraContainer("cassandra:3.11");
c.start();
// after
CassandraContainer c = new CassandraContainer("cassandra:3.11");
c.waitingFor(new CassandraQueryWaitStrategy().withStartupTimeout(Duration.ofMinutes(5)));
c.start();

// Ensure adequate resources; check Docker is healthy before starting
DockerClientFactory.instance().client();

try { container.start(); } catch (ContainerLaunchException e) { /* inspect container.getLogs(), retry once with longer timeout */ }

When it happens

Trigger: container.start() on a CassandraContainer whose configured wait strategy is CassandraQueryWaitStrategy and the node fails to accept a CQL query (e.g. via getDatabaseDelegate().execute("SELECT keyspace_name FROM system_schema.keyspaces")) before the timeout elapses.

Common situations: Slow machine or CI runners where Cassandra takes >60s to bootstrap; wrong image tag or JVM options causing the node to crash-loop; host port/resource exhaustion; storage driver issues.

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

• TIMEOUT_ERROR
• Timed out waiting for URL to be accessible
• Timed out waiting for log output matching
• Timed out waiting for container to execute
• Changing startup timeout is not supported with mode

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

Appendix: source

Thrown at modules/cassandra/src/main/java/org/testcontainers/cassandra/CassandraQueryWaitStrategy.java:50

                    getRateLimiter()
                        .doWhenReady(() -> {
                            try (DatabaseDelegate databaseDelegate = getDatabaseDelegate()) {
                                log.info("Checking connection is ready...");
                                ((CassandraDatabaseDelegate) databaseDelegate).execute(
                                        SELECT_VERSION_QUERY,
                                        StringUtils.EMPTY,
                                        1,
                                        false,
                                        false,
                                        true
                                    );
                            }
                        });
                    return true;
                }
            );
        } catch (TimeoutException e) {
            throw new ContainerLaunchException(TIMEOUT_ERROR);
        }
    }

    private DatabaseDelegate getDatabaseDelegate() {
        return new CassandraDatabaseDelegate(waitStrategyTarget);
    }
}

View on GitHub (pinned to 8e549514e3)