testcontainers/testcontainers-java · error · RuntimeException

${ex}

Error message

${ex}

What it means

YugabyteDBYSQLWaitStrategy probes YSQL readiness by executing an extended probe query via JDBC; any SQLException during the probe is wrapped in a RuntimeException with the SQLException as message/cause, failing the wait strategy attempt so it retries until timeout.

Solutions

1. Inspect the wrapped SQLException cause for the root error
2. Increase startup timeout so early connection-refused probes can retry
3. Verify YSQL port and default database/credentials on the container
4. Ensure the probe's DROP TABLE cleanup runs (container state isn't corrupting the probe DDL)

// warm the endpoint before strict waits
Duration timeout = Duration.ofMinutes(3);
container.waitingFor(new YugabyteDBYSQLWaitStrategy().withStartupTimeout(timeout));

try { container.start(); } catch (RuntimeException e) { if (e.getCause() instanceof SQLException sqlEx) { /* inspect sqlEx for readiness/auth issue */ } }

When it happens

Trigger: waitUntilReady's doWhenReady callback calls container.createConnection("") and executes YSQL_EXTENDED_PROBE; a SQLException (endpoint not up yet, auth failure, SQL error) triggers the wrap.

Common situations: YSQL (5433) not yet accepting connections during startup; wrong credentials; probe table already exists causing probe DDL failure; transient connection drops.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• container hasn't come up yet
• An exception while executing the internal check
• Can't find valid driver class for OceanBase
• Changing startup timeout is not supported with mode
• Container is started, but cannot be accessed by

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

Appendix: source

Thrown at modules/yugabytedb/src/main/java/org/testcontainers/containers/strategy/YugabyteDBYSQLWaitStrategy.java:51

    private static final String YSQL_EXTENDED_PROBE =
        "CREATE TABLE IF NOT EXISTS YB_SAMPLE(k int, v int, primary key(k, v))";

    private static final String YSQL_EXTENDED_PROBE_DROP_TABLE = "DROP TABLE IF EXISTS YB_SAMPLE";

    @Override
    public void waitUntilReady(WaitStrategyTarget target) {
        YugabyteDBYSQLContainer container = (YugabyteDBYSQLContainer) target;
        retryUntilSuccess(
            (int) startupTimeout.getSeconds(),
            TimeUnit.SECONDS,
            () -> {
                getRateLimiter()
                    .doWhenReady(() -> {
                        try (Connection con = container.createConnection(""); Statement stmt = con.createStatement()) {
                            stmt.execute(YSQL_EXTENDED_PROBE);
                            stmt.execute(YSQL_EXTENDED_PROBE_DROP_TABLE);
                        } catch (SQLException ex) {
                            throw new RuntimeException(ex);
                        }
                    });
                return true;
            }
        );
    }

    @Override
    public void waitUntilReady() {
        waitUntilReady(target);
    }
}

View on GitHub (pinned to 8e549514e3)