{"record":{"id":"66b596bbb0d33718","repo":"hibernate/hibernate-orm","slug":"entity-classes-s-and-s-share-the-entity-name","errorCode":null,"errorMessage":"Entity classes [%s] and [%s] share the entity name '%s' (entity names must be distinct)","messagePattern":"Entity classes \\[(.+?)\\] and \\[(.+?)\\] share the entity name '(.+?)' \\(entity names must be distinct\\)","errorType":"exception","errorClass":"DuplicateMappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":391,"sourceCode":"\t\treturn entityBindingMap;\n\t}\n\n\t@Override\n\tpublic PersistentClass getEntityBinding(String entityName) {\n\t\treturn entityBindingMap.get( entityName );\n\t}\n\n\t@Override\n\tpublic void addEntityBinding(PersistentClass persistentClass) throws DuplicateMappingException {\n\t\tfinal String entityName = persistentClass.getEntityName();\n\t\tfinal String jpaEntityName = persistentClass.getJpaEntityName();\n\t\tif ( entityBindingMap.containsKey( entityName ) ) {\n\t\t\tthrow new DuplicateMappingException( DuplicateMappingException.Type.ENTITY, entityName );\n\t\t}\n\n\t\tfor ( var existingPersistentClass : entityBindingMap.values() ) {\n\t\t\tif ( existingPersistentClass.getJpaEntityName().equals( jpaEntityName ) ) {\n\t\t\t\tthrow new DuplicateMappingException(\n\t\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\t\"Entity classes [%s] and [%s] share the entity name '%s' (entity names must be distinct)\",\n\t\t\t\t\t\t\t\texistingPersistentClass.getClassName(),\n\t\t\t\t\t\t\t\tpersistentClass.getClassName(),\n\t\t\t\t\t\t\t\tjpaEntityName\n\t\t\t\t\t\t),\n\t\t\t\t\t\tDuplicateMappingException.Type.ENTITY,\n\t\t\t\t\t\tjpaEntityName\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tentityBindingMap.put( entityName, persistentClass );\n\t}\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Collection handling\n","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L373-L409","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: two @Entity classes named User in different packages\npackage admin;  @Entity public class User {}\npackage audit;  @Entity public class User {}\n\n// after: explicit distinct entity names\npackage admin;  @Entity(name = \"AdminUser\") public class User {}\npackage audit;  @Entity(name = \"AuditUser\") public class User {}","handlingStrategy":"try-catch","validationCode":"// Fail fast when two mapped classes share a JPA entity name\nMap<String, Class<?>> byName = new HashMap<>();\nfor (Class<?> c : entityClasses) {\n    String n = jpaEntityName(c); // @Entity(name) value or simple class name\n    Class<?> prev = byName.put(n, c);\n    if (prev != null) {\n        throw new IllegalStateException(prev + \" and \" + c + \" share entity name '\" + n + \"'\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n}\ncatch (DuplicateMappingException e) {\n    if (e.getMessage().contains(\"share the entity name\")) {\n        // add an explicit @Entity(name=...) to one of the two classes listed\n    }\n}","preventionTips":["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"],"tags":["hibernate","jpa","entity-name","duplicate"],"backgroundTag":"duplicate-entity-name","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}