{"record":{"id":"360553477b2b1e86","repo":"hibernate/hibernate-orm","slug":"unable-to-build-hibernate-sessionfactory-persist","errorCode":null,"errorMessage":"Unable to build Hibernate SessionFactory  [persistence unit: {}] ","messagePattern":"Unable to build Hibernate SessionFactory  \\[persistence unit: (.+?)\\] ","errorType":"exception","errorClass":"PersistenceException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java","lineNumber":1646,"sourceCode":"\t\t}\n\t\tfinally {\n\t\t\t// release this builder\n\t\t\tcancel();\n\t\t}\n\t}\n\n\t@Override\n\tpublic EntityManagerFactory build() {\n\t\tboolean success = false;\n\t\ttry {\n\t\t\tfinal var sessionFactoryBuilder = populateSessionFactoryBuilder();\n\t\t\ttry {\n\t\t\t\tfinal var entityManagerFactory = sessionFactoryBuilder.build();\n\t\t\t\tsuccess = true;\n\t\t\t\treturn entityManagerFactory;\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new PersistenceException( \"Unable to build Hibernate SessionFactory \" + exceptionHeader() , e );\n\t\t\t}\n\t\t}\n\t\tfinally {\n\t\t\tif ( !success ) {\n\t\t\t\tcleanup();\n\t\t\t}\n\t\t}\n\t}\n\n\tprotected SessionFactoryBuilder populateSessionFactoryBuilder() {\n\t\tfinal var builder = metadata().getSessionFactoryBuilder();\n//\t\t// Locate and apply the requested SessionFactory-level interceptor (if one)\n//\t\tfinal Object sessionFactoryInterceptorSetting = configurationValues.remove( AvailableSettings.INTERCEPTOR );\n//\t\tif ( sessionFactoryInterceptorSetting != null ) {\n//\t\t\tfinal Interceptor sessionFactoryInterceptor =\n//\t\t\t\t\tstrategySelector.resolveStrategy( Interceptor.class, sessionFactoryInterceptorSetting );\n//\t\t\tbuilder.applyInterceptor( sessionFactoryInterceptor );\n//\t\t}","sourceCodeStart":1628,"sourceCodeEnd":1664,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java#L1628-L1664","documentation":"Thrown by EntityManagerFactoryBuilderImpl.build() as a PersistenceException when sessionFactoryBuilder.build() raises any exception while constructing the Hibernate SessionFactory for the persistence unit. It is a catch-all wrapper: the informative error is the cause, typically a mapping problem, missing dialect, unknown type, or service-registry failure. The builder's cleanup() runs afterwards, releasing the partially built factory and service registry.","triggerScenarios":"Calling entityManagerFactoryBuilder.build() (or Persistence.createEntityManagerFactory / Spring's LocalContainerEntityManagerFactoryBean) with invalid mapped classes (@Entity with no identifier, duplicate table/column names, unsupported attribute type), an unresolvable hibernate.dialect, a class listed in persistence.xml that is not an entity, or a second bootstrap reusing a closed service registry.","commonSituations":"Upgrading Hibernate major versions where old mapping metadata is no longer accepted; typo in hibernate.dialect; entities in a jar not visible to the persistence classloader; two persistence units sharing configuration keys; running against a database whose dialect was removed in a newer Hibernate release.","solutions":["Inspect the cause chain of the PersistenceException - Hibernate's inner exception (e.g. MappingException, NoSuchMethodError) pinpoints the failing class or setting.","Fix the specific mapping/setting reported in the cause (add @Id, correct the dialect FQCN, remove duplicate column mappings).","Enable org.hibernate.SQL and boot logging (org.hibernate.boot=DEBUG) to see the last successful boot step.","If the cause is a service error, check for conflicting hibernate-* jar versions on the classpath and align them on one version."],"exampleFix":"// before\n@Entity\npublic class Person { private String name; } // no @Id -> build() fails\n\n// after\n@Entity\npublic class Person {\n    @Id @GeneratedValue\n    private Long id;\n    private String name;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    return builder.build();\n} catch (PersistenceException e) {\n    // the cause chain holds the real mapping/DDL error - log it whole\n    log.error(\"EntityManagerFactory boot failed for unit {}: {}\", unitName, rootMessage(e));\n    throw e; // boot failure is unrecoverable; fail fast with diagnostics","preventionTips":["Boot the EntityManagerFactory in a smoke test so mapping errors surface in CI, not at deploy time.","Keep all hibernate-* artifacts on the same version via a BOM.","Turn on org.hibernate.boot=DEBUG locally to see the last mapping processed before a failure."],"tags":["hibernate","jpa","session-factory","bootstrap","persistence-unit","mapping"],"backgroundTag":"session-factory-bootstrap-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}