hibernate/hibernate-orm · error · SchemaManagementException

Error accessing user-provided Connection via JdbcConnectionA

Error message

Error accessing user-provided Connection via JdbcConnectionAccessProvidedConnectionImpl

What it means

The user-supplied-connection isolator caught an SQLException while obtaining the connection for schema management (jdbcContext.getJdbcConnectionAccess().obtainConnection()); it is rethrown as this SchemaManagementException with the SQLException as the cause. The real failure is an ordinary connectivity problem - unreachable database, rejected credentials, missing driver, pool timeout - surfacing through the schema tool.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/internal/DdlTransactionIsolatorProvidedConnectionImpl.java:52

	}

	@Override
	public Connection getIsolatedConnection() {
		return getIsolatedConnection(true);
	}

	@Override
	public Connection getIsolatedConnection(boolean autocommit) {
		try {
			Connection connection = jdbcContext.getJdbcConnectionAccess().obtainConnection();
			if ( connection.getAutoCommit() != autocommit ) {
				throw new SchemaManagementException( "User-provided Connection via JdbcConnectionAccessProvidedConnectionImpl has wrong auto-commit mode" );
			}
			return connection;
		}
		catch (SQLException e) {
			// should never happen
			throw new SchemaManagementException( "Error accessing user-provided Connection via JdbcConnectionAccessProvidedConnectionImpl", e );
		}
	}

	@Override
	public void release() {
		final var connectionAccess = jdbcContext.getJdbcConnectionAccess();
		if( !( connectionAccess instanceof JdbcConnectionAccessProvidedConnectionImpl ) ) {
			throw new IllegalStateException(
				"DdlTransactionIsolatorProvidedConnectionImpl should always use a JdbcConnectionAccessProvidedConnectionImpl"
			);
		}
		try {
			// While passing the connection to the releaseConnection method might be suitable for other `JdbcConnectionAccess` implementations,
			// it has no meaning for JdbcConnectionAccessProvidedConnectionImpl because, in this case, the connection is wrapped
			// and we don't have access to it upon releasing via the DdlTransactionIsolatorProvidedConnectionImpl.
			connectionAccess.releaseConnection( null );
		}
		catch (SQLException exception) {

View on GitHub (pinned to fad1729dce)

Solutions

Unwrap and read the cause (SQLException) - it names the actual problem (URL, auth, timeout, driver).
Verify basic connectivity with a plain DriverManager.getConnection(url, user, pass) probe in the same environment.
Add a database readiness check (container healthcheck / wait-for-it) before the schema step runs.
Confirm the JDBC driver artifact is on the runtime classpath and the URL matches the driver scheme.

Example fix

// before: schema export runs before the database is reachable
new SchemaUpdate(metadata, registry).execute(EnumSet.of(TargetType.DATABASE), ...);

// after: probe first, fail with a clear message, then run schema tooling
try (Connection c = DriverManager.getConnection(url, user, pass)) {
    // database is reachable
} catch (SQLException e) {
    throw new IllegalStateException("Database not ready for schema management", e);
}
new SchemaUpdate(metadata, registry).execute(EnumSet.of(TargetType.DATABASE), ...);

Defensive patterns

Strategy: try-catch

Validate before calling

// Probe connectivity before any schema tooling runs
try (Connection c = DriverManager.getConnection(jdbcUrl, user, pass)) {
    // reachable - proceed
} catch (SQLException e) {
    throw new IllegalStateException("Database not reachable at " + jdbcUrl + " - aborting schema management", e);
}

Try / catch

try {
    new SchemaExport(metadata).execute(targets, Action.CREATE, metadata, registry);
} catch (SchemaManagementException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Error accessing user-provided Connection")) {
        Throwable cause = e.getCause(); // the SQLException: URL/auth/driver/timeout
        // surface cause to ops dashboards; retry only after a readiness check passes
    }
    throw e;
}

Prevention

Gate schema steps on a database healthcheck (container depends_on with health condition)
Verify JDBC URL and credentials with a startup probe independent of Hibernate
Keep the JDBC driver on the runtime classpath and fail builds that silently drop it

When it happens

Trigger: Schema tooling executing with a provided connection where obtainConnection() throws: database down or not yet ready (CI containers), wrong JDBC URL after config refactors, authentication failure after credential rotation, connection pool exhausted/timeout, or 'No suitable driver' when the JDBC driver is missing from the classpath.

Common situations: CI pipeline starting schema export before the database container passes its healthcheck; rotated DB credentials not propagated; fat-jar packaging dropping the driver; HikariCP connectionTimeout during heavy parallel migrations.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/1131b5b6cf425556. Report an issue: GitHub.