hibernate/hibernate-orm · critical · HibernateException

Unable to access JDBC metadata

Error message

Unable to access JDBC metadata

What it means

JdbcEnvironmentInitiator queries JDBC DatabaseMetaData at startup to build the JdbcEnvironment (dialect resolution, type mappings). When hibernate.boot.allow_jdbc_metadata_access=require (JdbcMetadataOnBoot.REQUIRE), any exception while obtaining the connection or reading metadata is rethrown as HibernateException 'Unable to access JDBC metadata', aborting boot; with the default ALLOW it is only logged and Hibernate falls back to configured defaults.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/JdbcEnvironmentInitiator.java:428

									final String substring = version.substring( versionIndex + prefix.length() );
									final String micro = new StringTokenizer( substring, " .,-:;/()[]" ).nextToken();
									return parseInt(micro);
								}
								catch (NumberFormatException nfe) {
									return 0;
								}
							}
							else {
								return 0;
							}
						}
					},
					false
			);
		}
		catch ( Exception e ) {
			if ( jdbcMetadataAccess == JdbcMetadataOnBoot.REQUIRE ) {
				throw new HibernateException( "Unable to access JDBC metadata", e );
			}
			else {
				JDBC_LOGGER.unableToObtainConnectionToQueryMetadata( e );
			}
		}
		finally {
			//noinspection resource
			jdbcCoordinator.close();
		}
		// accessing the JDBC metadata failed
		return getJdbcEnvironmentWithDefaults( configurationValues, registry, dialectFactory );
	}

	private static void logDatabaseAndDriver(DatabaseMetaData dbmd) throws SQLException {
		if ( JDBC_LOGGER.isDebugEnabled() ) {
			JDBC_LOGGER.logDatabaseInfo(
					dbmd.getDatabaseProductName(),
					dbmd.getDatabaseProductVersion(),

View on GitHub (pinned to fad1729dce)

Solutions

  1. Fix the underlying connectivity: verify JDBC URL, credentials, driver on classpath, and that the database/pool is up before app start
  2. If failing fast is not desired, change hibernate.boot.allow_jdbc_metadata_access to allow (default) so Hibernate logs and uses defaults
  3. If you keep 'require', ensure the database is a hard startup dependency in your deployment ordering

Example fix

# before
hibernate.boot.allow_jdbc_metadata_access=require

# after (fall back to defaults when metadata is unavailable)
# hibernate.boot.allow_jdbc_metadata_access=allow  (or omit)
Defensive patterns

Strategy: validation

Validate before calling

// fail fast with a clear message before buildSessionFactory
try (Connection ignored = dataSource.getConnection()) {
    DatabaseMetaData md = ignored.getMetaData(); // proves metadata access works
}
catch (SQLException e) {
    throw new IllegalStateException("database not reachable for metadata access", e);
}

Try / catch

try {
    emf = Persistence.createEntityManagerFactory("pu");
}
catch (PersistenceException e) {
    if (e.getCause() instanceof HibernateException he
            && he.getMessage().contains("Unable to access JDBC metadata")) {
        // translate boot failure into infrastructure alert
        throw new StartupDependencyMissing("database unreachable at boot", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Setting hibernate.boot.allow_jdbc_metadata_access=require while the database is unreachable, credentials are wrong, the JDBC driver class is missing, or the pool cannot supply a connection during SessionFactory build.

Common situations: Teams set 'require' deliberately so misconfigured environments fail fast at boot; then the DB is down at deployment, the URL changed, or a firewall blocks it, and startup crashes instead of degrading.

Related errors

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