hibernate/hibernate-orm · error · DuplicateMappingException

Entity classes [%s] and [%s] share the entity name '%s' (ent

Error message

Entity classes [%s] and [%s] share the entity name '%s' (entity names must be distinct)

What it means

Besides the internal entity name, Hibernate enforces uniqueness of the JPA entity name (the unqualified simple class name by default, or the @Entity(name) value). addEntityBinding scans all existing bindings and throws DuplicateMappingException listing both class names when a different class already registered the same JPA entity name - entity names must be distinct for JPQL/HQL resolution.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:391

		return entityBindingMap;
	}

	@Override
	public PersistentClass getEntityBinding(String entityName) {
		return entityBindingMap.get( entityName );
	}

	@Override
	public void addEntityBinding(PersistentClass persistentClass) throws DuplicateMappingException {
		final String entityName = persistentClass.getEntityName();
		final String jpaEntityName = persistentClass.getJpaEntityName();
		if ( entityBindingMap.containsKey( entityName ) ) {
			throw new DuplicateMappingException( DuplicateMappingException.Type.ENTITY, entityName );
		}

		for ( var existingPersistentClass : entityBindingMap.values() ) {
			if ( existingPersistentClass.getJpaEntityName().equals( jpaEntityName ) ) {
				throw new DuplicateMappingException(
						String.format(
								"Entity classes [%s] and [%s] share the entity name '%s' (entity names must be distinct)",
								existingPersistentClass.getClassName(),
								persistentClass.getClassName(),
								jpaEntityName
						),
						DuplicateMappingException.Type.ENTITY,
						jpaEntityName
				);
			}
		}

		entityBindingMap.put( entityName, persistentClass );
	}

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Collection handling

View on GitHub (pinned to fad1729dce)

Solutions

Give one of the two classes named in the message an explicit unique @Entity(name="...") and update JPQL/HQL references
Rename one of the conflicting classes so the simple names differ
If both entities are needed under the same name, split them into separate persistence units / SessionFactories

Example fix

// before: two @Entity classes named User in different packages
package admin;  @Entity public class User {}
package audit;  @Entity public class User {}

// after: explicit distinct entity names
package admin;  @Entity(name = "AdminUser") public class User {}
package audit;  @Entity(name = "AuditUser") public class User {}

Defensive patterns

Strategy: try-catch

Validate before calling

// Fail fast when two mapped classes share a JPA entity name
Map<String, Class<?>> byName = new HashMap<>();
for (Class<?> c : entityClasses) {
    String n = jpaEntityName(c); // @Entity(name) value or simple class name
    Class<?> prev = byName.put(n, c);
    if (prev != null) {
        throw new IllegalStateException(prev + " and " + c + " share entity name '" + n + "'");
    }
}

Try / catch

try {
    metadata.buildSessionFactory();
}
catch (DuplicateMappingException e) {
    if (e.getMessage().contains("share the entity name")) {
        // add an explicit @Entity(name=...) to one of the two classes listed
    }
}

Prevention

Give commonly-named entities (User, Role, Event) explicit @Entity(name) values up front
Add a CI scan that collects @Entity names and fails on duplicates

When it happens

Trigger: Two @Entity classes in different packages with the same simple name (both default to that name as JPA entity name); or an explicit @Entity(name="X") colliding with another entity's default or explicit name; the loop at InFlightMetadataCollectorImpl.java:388-398 finds the clash.

Common situations: Commonly-named classes like User, Role, Address or Event defined in two packages or modules; refactoring that moved a class but kept an old @Entity(name); bulk copy of entities into a new package.

Related errors

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