{"record":{"id":"aad37c1b946e2fc8","repo":"testcontainers/testcontainers-java","slug":"could-not-obtain-jdbc-connection","errorCode":null,"errorMessage":"Could not obtain JDBC connection","messagePattern":"Could not obtain JDBC connection","errorType":"exception","errorClass":"ConnectionCreationException","httpStatus":null,"severity":"error","filePath":"modules/jdbc/src/main/java/org/testcontainers/jdbc/JdbcDatabaseDelegate.java","lineNumber":37,"sourceCode":"    private JdbcDatabaseContainer container;\n\n    private Connection connection;\n\n    private String queryString;\n\n    public JdbcDatabaseDelegate(JdbcDatabaseContainer container, String queryString) {\n        this.container = container;\n        this.queryString = queryString;\n    }\n\n    @Override\n    protected Statement createNewConnection() {\n        try {\n            connection = container.createConnection(queryString);\n            return connection.createStatement();\n        } catch (SQLException e) {\n            log.error(\"Could not obtain JDBC connection\");\n            throw new ConnectionCreationException(\"Could not obtain JDBC connection\", e);\n        }\n    }\n\n    @Override\n    public void execute(\n        String statement,\n        String scriptPath,\n        int lineNumber,\n        boolean continueOnError,\n        boolean ignoreFailedDrops\n    ) {\n        try {\n            boolean rowsAffected = getConnection().execute(statement);\n            log.debug(\"{} returned as updateCount for SQL: {}\", rowsAffected, statement);\n        } catch (SQLException ex) {\n            boolean dropStatement = statement.trim().toLowerCase().startsWith(\"drop\");\n            if (continueOnError || (dropStatement && ignoreFailedDrops)) {\n                log.debug(","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/jdbc/src/main/java/org/testcontainers/jdbc/JdbcDatabaseDelegate.java#L19-L55","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nJdbcDatabaseDelegate d = new JdbcDatabaseDelegate(container, \"\");\nd.execute(\"SELECT 1\", 0, null, null); // container not started\n// after\ncontainer.start();\nJdbcDatabaseDelegate d = new JdbcDatabaseDelegate(container, \"\");\nd.execute(\"SELECT 1\", 0, null, null);","handlingStrategy":"validation","validationCode":"if (!container.isRunning()) {\n    container.start();\n}","typeGuard":null,"tryCatchPattern":"try {\n    delegate.execute(statement, 0, null, null);\n} catch (ConnectionCreationException e) {\n    log.error(\"Container connection failed: {}\", e.getCause() == null ? e : e.getCause().getMessage());\n    throw e;\n}","preventionTips":["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"],"tags":["jdbc","testcontainers","connection","docker"],"backgroundTag":"connection-refused","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}