{"record":{"id":"96ff3c31ceda5b28","repo":"hibernate/hibernate-orm","slug":"unable-to-access-jdbc-metadata","errorCode":null,"errorMessage":"Unable to access JDBC metadata","messagePattern":"Unable to access JDBC metadata","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/JdbcEnvironmentInitiator.java","lineNumber":428,"sourceCode":"\t\t\t\t\t\t\t\t\tfinal String substring = version.substring( versionIndex + prefix.length() );\n\t\t\t\t\t\t\t\t\tfinal String micro = new StringTokenizer( substring, \" .,-:;/()[]\" ).nextToken();\n\t\t\t\t\t\t\t\t\treturn parseInt(micro);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tcatch (NumberFormatException nfe) {\n\t\t\t\t\t\t\t\t\treturn 0;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\telse {\n\t\t\t\t\t\t\t\treturn 0;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t},\n\t\t\t\t\tfalse\n\t\t\t);\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tif ( jdbcMetadataAccess == JdbcMetadataOnBoot.REQUIRE ) {\n\t\t\t\tthrow new HibernateException( \"Unable to access JDBC metadata\", e );\n\t\t\t}\n\t\t\telse {\n\t\t\t\tJDBC_LOGGER.unableToObtainConnectionToQueryMetadata( e );\n\t\t\t}\n\t\t}\n\t\tfinally {\n\t\t\t//noinspection resource\n\t\t\tjdbcCoordinator.close();\n\t\t}\n\t\t// accessing the JDBC metadata failed\n\t\treturn getJdbcEnvironmentWithDefaults( configurationValues, registry, dialectFactory );\n\t}\n\n\tprivate static void logDatabaseAndDriver(DatabaseMetaData dbmd) throws SQLException {\n\t\tif ( JDBC_LOGGER.isDebugEnabled() ) {\n\t\t\tJDBC_LOGGER.logDatabaseInfo(\n\t\t\t\t\tdbmd.getDatabaseProductName(),\n\t\t\t\t\tdbmd.getDatabaseProductVersion(),","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/jdbc/env/internal/JdbcEnvironmentInitiator.java#L410-L446","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the underlying connectivity: verify JDBC URL, credentials, driver on classpath, and that the database/pool is up before app start","If failing fast is not desired, change hibernate.boot.allow_jdbc_metadata_access to allow (default) so Hibernate logs and uses defaults","If you keep 'require', ensure the database is a hard startup dependency in your deployment ordering"],"exampleFix":"# before\nhibernate.boot.allow_jdbc_metadata_access=require\n\n# after (fall back to defaults when metadata is unavailable)\n# hibernate.boot.allow_jdbc_metadata_access=allow  (or omit)","handlingStrategy":"validation","validationCode":"// fail fast with a clear message before buildSessionFactory\ntry (Connection ignored = dataSource.getConnection()) {\n    DatabaseMetaData md = ignored.getMetaData(); // proves metadata access works\n}\ncatch (SQLException e) {\n    throw new IllegalStateException(\"database not reachable for metadata access\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    emf = Persistence.createEntityManagerFactory(\"pu\");\n}\ncatch (PersistenceException e) {\n    if (e.getCause() instanceof HibernateException he\n            && he.getMessage().contains(\"Unable to access JDBC metadata\")) {\n        // translate boot failure into infrastructure alert\n        throw new StartupDependencyMissing(\"database unreachable at boot\", e);\n    }\n    throw e;\n}","preventionTips":["Only set allow_jdbc_metadata_access=require when the DB is a hard startup dependency","Verify URL/credentials/pool in a pre-boot health check","Order deployments so the database is up before the application starts"],"tags":["boot","jdbc-metadata","connection","configuration","hibernate"],"backgroundTag":"jdbc-metadata-access-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}