{"record":{"id":"02c383d771261cce","repo":"theonedev/onedev","slug":"failed-to-create-database-connection-driver-s","errorCode":null,"errorMessage":"Failed to create database connection (driver: %s, url: %s)","messagePattern":"Failed to create database connection \\(driver: (.+?), url: (.+?)\\)","errorType":"http","errorClass":"ExplicitException","httpStatus":400,"severity":"critical","filePath":"server-core/src/main/java/io/onedev/server/persistence/PersistenceUtils.java","lineNumber":42,"sourceCode":"\tprivate static final Logger logger = LoggerFactory.getLogger(PersistenceUtils.class);\n\t\n\tpublic static Connection openConnection(HibernateConfig hibernateConfig, ClassLoader classLoader) {\n\t\ttry {\n\t\t\tDriver driver = (Driver) Class.forName(hibernateConfig.getDriver(), true, classLoader).getDeclaredConstructor().newInstance();\n\t\t\tProperties connectProps = new Properties();\n\t\t\tString user = hibernateConfig.getUser();\n\t\t\tString password = hibernateConfig.getPassword();\n\t\t\tif (user != null)\n\t\t\t\tconnectProps.put(\"user\", user);\n\t\t\tif (password != null)\n\t\t\t\tconnectProps.put(\"password\", password);\n\n\t\t\tvar conn = driver.connect(hibernateConfig.getUrl(), connectProps);\n\t\t\tif (conn == null) {\n\t\t\t\tvar errorMessage = String.format(\n\t\t\t\t\t\t\"Failed to create database connection (driver: %s, url: %s)\",\n\t\t\t\t\t\thibernateConfig.getDriver(), hibernateConfig.getUrl());\n\t\t\t\tthrow new ExplicitException(errorMessage);\n\t\t\t}\n\t\t\treturn conn;\n\t\t} catch (Exception e) {\n\t\t\tthrow unchecked(e);\n\t\t}\n\t}\n\n\tpublic static <T> T callWithTransaction(Connection conn, Callable<T> callable) {\n\t\ttry {\n\t\t\tconn.setAutoCommit(false);\n\t\t\tconn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);\n\t\t\ttry {\n\t\t\t\tT result = callable.call();\n\t\t\t\tconn.commit();\n\t\t\t\treturn result;\n\t\t\t} catch (Exception e) {\n\t\t\t\tconn.rollback();\n\t\t\t\tthrow unchecked(e);","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/persistence/PersistenceUtils.java#L24-L60","documentation":"PersistenceUtils.openConnection() instantiates the configured JDBC driver and calls driver.connect(url, props). JDBC drivers return null (rather than throwing) when the URL is not acceptable to them, so OneDev converts that null into an ExplicitException 'Failed to create database connection (driver: ..., url: ...)'. It means the driver loaded fine but does not recognize/accept the configured URL, or the driver silently refused to connect.","triggerScenarios":"driver.connect() returns null because the JDBC URL does not match the driver's accepted URL prefix (e.g. using mysql driver with a postgres URL, malformed jdbc: URL, wrong driver class configured for the database type).","commonSituations":"Mismatched driver/URL pair in hibernate config (site DB config or bootstrap override); typo in jdbc: prefix; wrong driver class name set in config; custom site/lib driver jar that rejects the URL.","solutions":["Verify the JDBC URL prefix matches the configured driver (e.g. jdbc:postgresql:// for org.postgresql.Driver, jdbc:mysql:// for MySQL driver)","Check the DB type and driver setting in the OneDev database configuration and correct any mismatch","Test the same URL/user/password with a standalone JDBC client or `java -cp <driver.jar>` snippet","If using a custom driver in site/lib, confirm it supports the server DB version and URL format"],"exampleFix":"// before (mismatched)\njdbc:mysql://localhost:5432/onedev with org.postgresql.Driver\n// after\njdbc:postgresql://localhost:5432/onedev with org.postgresql.Driver","handlingStrategy":"validation","validationCode":"String url = hibernateConfig.getUrl();\nString driver = hibernateConfig.getDriver();\nif (url.startsWith(\"jdbc:postgresql\") != driver.contains(\"postgresql\")\n    || !url.startsWith(\"jdbc:\")) {\n    throw new IllegalArgumentException(\"Driver/URL mismatch: \" + driver + \" vs \" + url);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Connection conn = PersistenceUtils.openConnection(cfg, classLoader);\n} catch (ExplicitException | RuntimeException e) {\n    logger.error(\"DB connection failed: {}\", e.getMessage());\n    // prompt user to fix DB config\n}","preventionTips":["Match driver class to DB type and jdbc: URL prefix","Validate DB config at setup time before bootstrapping","Test credentials/URL with a standalone JDBC client first","Keep custom drivers in site/lib compatible with the server DB version"],"tags":["jdbc","database","configuration"],"backgroundTag":"connection-refused","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}