{"record":{"id":"7ed7c94fe2c7af1b","repo":"hibernate/hibernate-orm","slug":"duplicate-entity-definition-s","errorCode":null,"errorMessage":"Duplicate entity definition '%s'","messagePattern":"Duplicate entity definition '(.+?)'","errorType":"exception","errorClass":"DuplicateMappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":386,"sourceCode":"\t\treturn entityBindingMap.values();\n\t}\n\n\t@Override\n\tpublic Map<String, PersistentClass> getEntityBindingMap() {\n\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 );","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L368-L404","documentation":"Entities are registered in the InFlightMetadataCollector keyed by their Hibernate entity name (the fully-qualified class name unless overridden). addEntityBinding throws DuplicateMappingException(Type.ENTITY) with 'Duplicate entity definition' when an entity name is already present in entityBindingMap - the same entity name was mapped twice.","triggerScenarios":"The same entity name mapped through two channels: a class listed both as annotated class and via hbm.xml resource; duplicate <mapping class=...> or persistence.xml <class> entries; two mappings declaring the same explicit entity name; or programmatic addEntityBinding called twice for the same name.","commonSituations":"persistence.xml <class> plus hibernate.cfg.xml <mapping resource> for the same entity; module merges where two modules both map a shared entity; copy-pasted mapping entries; wildcard scanning pulling the same resource twice.","solutions":["Locate the duplicate named in the message: check every <mapping> element in cfg.xml, <class> in persistence.xml, and every MetadataSources.addAnnotatedClassName/addResource call","Remove the duplicate so each entity is mapped through exactly one source","If two genuinely different mappings must coexist, give one an explicit distinct entity name (@Entity(name=...) / <class name=...>)","When adding classes programmatically, deduplicate with a Set before adding"],"exampleFix":"<!-- before: same entity mapped twice -->\n<mapping class=\"com.acme.User\"/>\n<mapping resource=\"com/acme/User.hbm.xml\"/>\n\n<!-- after: exactly one mapping per entity -->\n<mapping class=\"com.acme.User\"/>","handlingStrategy":"try-catch","validationCode":"// Deduplicate programmatic mapping sources before adding\nSet<String> unique = new LinkedHashSet<>(annotatedClassNames);\nannotatedClassNames.clear();\nannotatedClassNames.addAll(unique);","typeGuard":null,"tryCatchPattern":"try {\n    SessionFactory sf = metadata.buildSessionFactory();\n}\ncatch (DuplicateMappingException e) {\n    // e.getMessage() names the duplicated entity: find the second mapping\n    // (cfg.xml <mapping>, persistence.xml <class>, hbm.xml, programmatic) and remove it\n}","preventionTips":["Map each entity through exactly one channel (annotations OR hbm.xml, never both)","When adding a new mapping, grep all cfg.xml/persistence.xml/programmatic sources for that entity name first"],"tags":["hibernate","entity-mapping","duplicate","bootstrap"],"backgroundTag":"duplicate-entity-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}