What causes "Could not obtain JDBC connection" in testcontainers/testcontainers-java?

Ensure the container is started and fully initialized before executing SQL (wait strategy / startup timeout)

testcontainers/testcontainers-java · error · ConnectionCreationException

Could not obtain JDBC connection

Error message

Could not obtain JDBC connection

What it means

JdbcDatabaseDelegate's createNewConnection throws ConnectionCreationException when container.createConnection(queryString) or createStatement() throws SQLException. It means the container-backed database connection could not be established for executing delegated SQL (e.g. init scripts).

Solutions

Ensure the container is started and fully initialized before executing SQL (wait strategy / startup timeout)
Check the chained SQLException cause for the vendor-level reason (auth, unknown DB, port)
Verify credentials and database name in the container configuration
Confirm Docker is running and the mapped host port is reachable

Example fix

// before
JdbcDatabaseDelegate d = new JdbcDatabaseDelegate(container, "");
d.execute("SELECT 1", 0, null, null); // container not started
// after
container.start();
JdbcDatabaseDelegate d = new JdbcDatabaseDelegate(container, "");
d.execute("SELECT 1", 0, null, null);

Defensive patterns

Strategy: validation

Validate before calling

if (!container.isRunning()) {
    container.start();
}

Try / catch

try {
    delegate.execute(statement, 0, null, null);
} catch (ConnectionCreationException e) {
    log.error("Container connection failed: {}", e.getCause() == null ? e : e.getCause().getMessage());
    throw e;
}

Prevention

Always start containers before delegating SQL to them
Set a sufficient startup timeout / wait strategy for the DB image
Verify Docker is available and ports are reachable in the environment

When it happens

Trigger: Executing statements via the delegate while the container is not started, the mapped port is not ready, credentials/query string are wrong, or the database inside the container refuses the connection.

Common situations: Running init scripts before container.start(); container still bootstrapping (startup timeout too low); wrong TC_ query parameters; Docker not running or mapped host port unreachable.

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

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

Appendix: source

Thrown at modules/jdbc/src/main/java/org/testcontainers/jdbc/JdbcDatabaseDelegate.java:37

    private JdbcDatabaseContainer container;

    private Connection connection;

    private String queryString;

    public JdbcDatabaseDelegate(JdbcDatabaseContainer container, String queryString) {
        this.container = container;
        this.queryString = queryString;
    }

    @Override
    protected Statement createNewConnection() {
        try {
            connection = container.createConnection(queryString);
            return connection.createStatement();
        } catch (SQLException e) {
            log.error("Could not obtain JDBC connection");
            throw new ConnectionCreationException("Could not obtain JDBC connection", e);
        }
    }

    @Override
    public void execute(
        String statement,
        String scriptPath,
        int lineNumber,
        boolean continueOnError,
        boolean ignoreFailedDrops
    ) {
        try {
            boolean rowsAffected = getConnection().execute(statement);
            log.debug("{} returned as updateCount for SQL: {}", rowsAffected, statement);
        } catch (SQLException ex) {
            boolean dropStatement = statement.trim().toLowerCase().startsWith("drop");
            if (continueOnError || (dropStatement && ignoreFailedDrops)) {
                log.debug(

View on GitHub (pinned to 8e549514e3)