hibernate/hibernate-orm · error · PersistenceException

No name provided and multiple persistence units found

Error message

No name provided and multiple persistence units found

What it means

HibernatePersistenceProvider.getEntityManagerFactoryBuilderOrNull scans META-INF/persistence.xml resources and, when the caller supplied no persistence-unit name and more than one unit was found, refuses to guess and throws this PersistenceException. Exactly one candidate (or an explicit name) is required to bootstrap an EntityManagerFactory.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java:98

				persistenceUnitName,
				properties,
				null,
				null
		);
	}

	private EntityManagerFactoryBuilder getEntityManagerFactoryBuilderOrNull(
			String persistenceUnitName,
			Map<?,?> properties,
			@Nullable ClassLoader providedClassLoader,
			@Nullable ClassLoaderService providedClassLoaderService) {
		JPA_LOGGER.attemptingToObtainEmfBuilder( persistenceUnitName );
		final var integration = wrap( properties );
		final var units = locatePersistenceUnits( integration, providedClassLoader, providedClassLoaderService );
		JPA_LOGGER.locatedAndParsedPersistenceUnits( units.size() );
		if ( persistenceUnitName == null && units.size() > 1 ) {
			// no persistence-unit name was specified, and we found multiple persistence-units
			throw new PersistenceException( "No name provided and multiple persistence units found" );
		}

		for ( var persistenceUnit : units ) {
			if ( JPA_LOGGER.isTraceEnabled() ) {
				JPA_LOGGER.checkingPersistenceUnitName(
						persistenceUnit.getName(),
						persistenceUnit.getProviderClassName(),
						persistenceUnitName
				);
			}

			final boolean matches =
					persistenceUnitName == null
					|| persistenceUnit.getName().equals( persistenceUnitName );
			if ( matches ) {
				// See if we (Hibernate) are the persistence provider
				if ( isProvider( persistenceUnit, properties ) ) {
					return providedClassLoaderService == null

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass the explicit unit name: Persistence.createEntityManagerFactory("main") or setPersistenceUnitName("main") / @PersistenceContext(unitName = "main")
2. Locate the stray persistence.xml (search the dependency tree / packaged jar) and remove, relocate, or rename the unit
3. If several units are intentional, always configure consumers with an explicit unit name

Example fix

// before
EntityManagerFactory emf = Persistence.createEntityManagerFactory(null); // ambiguous

// after
EntityManagerFactory emf = Persistence.createEntityManagerFactory("main"); // matches <persistence-unit name="main">

ClassLoader cl = Thread.currentThread().getContextClassLoader();
int units = 0;
for (java.net.URL url : java.util.Collections.list(cl.getResources("META-INF/persistence.xml"))) {
    units++;
}
if (units > 1 && unitName == null) {
    throw new IllegalStateException("Persistence unit name required; " + units + " persistence.xml files on classpath");
}

When it happens

Trigger: Persistence.createEntityManagerFactory called with a null/empty unit name, or a Spring LocalContainerEntityManagerFactoryBean with no persistenceUnitName, while the classpath contains multiple persistence.xml files or a single file with several <persistence-unit> entries.

Common situations: Adding a dependency JAR that ships its own META-INF/persistence.xml; multi-module deployments merged into one classpath; fat/uber-jars aggregating several JPA modules; test classpaths pulling in another module's persistence.xml.

Related errors

• Association '${path}' targets the type '${type}' which does
• Unable to build Hibernate SessionFactory [persistence unit:
• AttributeConverter class [%s] registered multiple times
• Duplicate named query '%s'
• Duplicate named stored procedure '{}'

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