{"record":{"id":"59804ae5226dcc61","repo":"testcontainers/testcontainers-java","slug":"could-not-create-new-connection","errorCode":null,"errorMessage":"Could not create new connection","messagePattern":"Could not create new connection","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"modules/jdbc/src/main/java/org/testcontainers/containers/JdbcDatabaseContainer.java","lineNumber":296,"sourceCode":"                try {\n                    logger()\n                        .debug(\n                            \"Trying to create JDBC connection using {} to {} with properties: {}\",\n                            jdbcDriverInstance.getClass().getName(),\n                            url,\n                            properties\n                        );\n\n                    return jdbcDriverInstance.connect(url, properties);\n                } catch (SQLException e) {\n                    lastException = e;\n                    Thread.sleep(100L);\n                }\n            }\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n        }\n        throw new SQLException(\"Could not create new connection\", lastException);\n    }\n\n    /**\n     * Template method for constructing the JDBC URL to be used for creating {@link Connection}s.\n     * This should be overridden if the JDBC URL and query string concatenation or URL string\n     * construction needs to be different to normal.\n     *\n     * @param queryString query string parameters that should be appended to the JDBC connection URL.\n     *                    The '?' character must be included\n     * @return a full JDBC URL including queryString\n     */\n    protected String constructUrlForConnection(String queryString) {\n        String baseUrl = getJdbcUrl();\n\n        if (\"\".equals(queryString)) {\n            return baseUrl;\n        }\n","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/jdbc/src/main/java/org/testcontainers/containers/JdbcDatabaseContainer.java#L278-L314","documentation":"createConnection(String) retries DriverManager.getConnection with a fresh JDBC URL until a retry limit; once exhausted it throws SQLException('Could not create new connection') with the last exception as cause. Unlike the wait-phase error, this happens on explicit connection creation after/during use.","triggerScenarios":"All retry attempts of creating a Connection fail (network, auth, URL, or DB not accepting connections) within createConnection's retry loop.","commonSituations":"Wrong credentials in withUsername/withPassword; database stopped or crashed mid-test; connection URL parameters invalid; connection pool exhaustion or network policy blocking the mapped port.","solutions":["Read the cause (lastException) to see the real failure (auth refused, unknown db, timeout)","Verify username/password/database name match the container configuration","Ensure the container is running and the mapped port is reachable from the test","Check container logs for database-side errors"],"exampleFix":"// before\ncontainer.withUsername(\"wrong\").withPassword(\"wrong\");\n// after\ncontainer.withUsername(\"test\").withPassword(\"test\").withDatabaseName(\"test\");","handlingStrategy":"try-catch","validationCode":"// verify reachability first\ntry (var probe = DriverManager.getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword())) { /* ok */ }","typeGuard":null,"tryCatchPattern":"try { conn = container.createConnection(\"?\"); } catch (SQLException e) { Throwable cause = e.getCause(); /* inspect cause: auth vs network vs DB error */ }","preventionTips":["Double-check username/password/database name against image env config","Keep the container running for the duration of all connections","Log the cause chain; the wrapped lastException has the real reason"],"tags":["jdbc","connection","sql"],"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"}