theonedev/onedev · critical · ExplicitException

Failed to create database connection (driver: %s, url: %s)

Error message

Failed to create database connection (driver: %s, url: %s)

What it means

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.

Source

Thrown at server-core/src/main/java/io/onedev/server/persistence/PersistenceUtils.java:42

	private static final Logger logger = LoggerFactory.getLogger(PersistenceUtils.class);
	
	public static Connection openConnection(HibernateConfig hibernateConfig, ClassLoader classLoader) {
		try {
			Driver driver = (Driver) Class.forName(hibernateConfig.getDriver(), true, classLoader).getDeclaredConstructor().newInstance();
			Properties connectProps = new Properties();
			String user = hibernateConfig.getUser();
			String password = hibernateConfig.getPassword();
			if (user != null)
				connectProps.put("user", user);
			if (password != null)
				connectProps.put("password", password);

			var conn = driver.connect(hibernateConfig.getUrl(), connectProps);
			if (conn == null) {
				var errorMessage = String.format(
						"Failed to create database connection (driver: %s, url: %s)",
						hibernateConfig.getDriver(), hibernateConfig.getUrl());
				throw new ExplicitException(errorMessage);
			}
			return conn;
		} catch (Exception e) {
			throw unchecked(e);
		}
	}

	public static <T> T callWithTransaction(Connection conn, Callable<T> callable) {
		try {
			conn.setAutoCommit(false);
			conn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);
			try {
				T result = callable.call();
				conn.commit();
				return result;
			} catch (Exception e) {
				conn.rollback();
				throw unchecked(e);

View on GitHub (pinned to d44925c47c)

Solutions

1. Verify the JDBC URL prefix matches the configured driver (e.g. jdbc:postgresql:// for org.postgresql.Driver, jdbc:mysql:// for MySQL driver)
2. Check the DB type and driver setting in the OneDev database configuration and correct any mismatch
3. Test the same URL/user/password with a standalone JDBC client or `java -cp <driver.jar>` snippet
4. If using a custom driver in site/lib, confirm it supports the server DB version and URL format

Example fix

// before (mismatched)
jdbc:mysql://localhost:5432/onedev with org.postgresql.Driver
// after
jdbc:postgresql://localhost:5432/onedev with org.postgresql.Driver

String url = hibernateConfig.getUrl();
String driver = hibernateConfig.getDriver();
if (url.startsWith("jdbc:postgresql") != driver.contains("postgresql")
    || !url.startsWith("jdbc:")) {
    throw new IllegalArgumentException("Driver/URL mismatch: " + driver + " vs " + url);
}

try {
    Connection conn = PersistenceUtils.openConnection(cfg, classLoader);
} catch (ExplicitException | RuntimeException e) {
    logger.error("DB connection failed: {}", e.getMessage());
    // prompt user to fix DB config
}

When it happens

Trigger: 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).

Common situations: 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.

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

• Unrecognized command:
• Unable to discover cluster ip from database connection url:
• Time tracking needs to be enabled for the project
• Link spec not found: ${linkName}
• Upload project not found:

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/02c383d771261cce. Report an issue: GitHub.