hibernate/hibernate-orm · critical · PersistenceException

Unable to build Hibernate SessionFactory [persistence unit:

Error message

Unable to build Hibernate SessionFactory  [persistence unit: {}] 

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java:1646

		}
		finally {
			// release this builder
			cancel();
		}
	}

	@Override
	public EntityManagerFactory build() {
		boolean success = false;
		try {
			final var sessionFactoryBuilder = populateSessionFactoryBuilder();
			try {
				final var entityManagerFactory = sessionFactoryBuilder.build();
				success = true;
				return entityManagerFactory;
			}
			catch (Exception e) {
				throw new PersistenceException( "Unable to build Hibernate SessionFactory " + exceptionHeader() , e );
			}
		}
		finally {
			if ( !success ) {
				cleanup();
			}
		}
	}

	protected SessionFactoryBuilder populateSessionFactoryBuilder() {
		final var builder = metadata().getSessionFactoryBuilder();
//		// Locate and apply the requested SessionFactory-level interceptor (if one)
//		final Object sessionFactoryInterceptorSetting = configurationValues.remove( AvailableSettings.INTERCEPTOR );
//		if ( sessionFactoryInterceptorSetting != null ) {
//			final Interceptor sessionFactoryInterceptor =
//					strategySelector.resolveStrategy( Interceptor.class, sessionFactoryInterceptorSetting );
//			builder.applyInterceptor( sessionFactoryInterceptor );
//		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Inspect the cause chain of the PersistenceException - Hibernate's inner exception (e.g. MappingException, NoSuchMethodError) pinpoints the failing class or setting.
2. Fix the specific mapping/setting reported in the cause (add @Id, correct the dialect FQCN, remove duplicate column mappings).
3. Enable org.hibernate.SQL and boot logging (org.hibernate.boot=DEBUG) to see the last successful boot step.
4. If the cause is a service error, check for conflicting hibernate-* jar versions on the classpath and align them on one version.

Example fix

// before
@Entity
public class Person { private String name; } // no @Id -> build() fails

// after
@Entity
public class Person {
    @Id @GeneratedValue
    private Long id;
    private String name;
}

try {
    return builder.build();
} catch (PersistenceException e) {
    // the cause chain holds the real mapping/DDL error - log it whole
    log.error("EntityManagerFactory boot failed for unit {}: {}", unitName, rootMessage(e));
    throw e; // boot failure is unrecoverable; fail fast with diagnostics

When it happens

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

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

Related errors

• Attribute was not a Map : ${collectionMemberType}
• Unable to create AttributeConverter instance
• Association '${path}' targets the type '${type}' which does
• Could not resolve PropertyAccess for attribute `%s#%s`
• Could not resolve PropertyAccess for attribute `%s#%s`

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