{"record":{"id":"8520aeb8205888f7","repo":"hibernate/hibernate-orm","slug":"duplicate-collection-definition-s","errorCode":null,"errorMessage":"Duplicate collection definition '%s'","messagePattern":"Duplicate collection definition '(.+?)'","errorType":"exception","errorClass":"DuplicateMappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":424,"sourceCode":"\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Collection handling\n\n\t@Override\n\tpublic java.util.Collection<Collection> getCollectionBindings() {\n\t\treturn collectionBindingMap.values();\n\t}\n\n\t@Override\n\tpublic Collection getCollectionBinding(String role) {\n\t\treturn collectionBindingMap.get( role );\n\t}\n\n\t@Override\n\tpublic void addCollectionBinding(Collection collection) throws DuplicateMappingException {\n\t\tfinal String collectionRole = collection.getRole();\n\t\tif ( collectionBindingMap.containsKey( collectionRole ) ) {\n\t\t\tthrow new DuplicateMappingException( DuplicateMappingException.Type.COLLECTION, collectionRole );\n\t\t}\n\t\tcollectionBindingMap.put( collectionRole, collection );\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Hibernate Type handling\n\n\n\t@Override\n\tpublic TypeDefinitionRegistry getTypeDefinitionRegistry() {\n\t\treturn typeDefRegistry;\n\t}\n\n\t@Override\n\tpublic TypeDefinition getTypeDefinition(String registrationKey) {\n\t\treturn typeDefRegistry.resolve( registrationKey );\n\t}","sourceCodeStart":406,"sourceCodeEnd":442,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L406-L442","documentation":"Collections are registered by role string 'EntityName.propertyName'. addCollectionBinding throws DuplicateMappingException(Type.COLLECTION) with 'Duplicate collection definition' when a mapping tries to register a collection role that is already present in collectionBindingMap - the same collection property has been mapped twice.","triggerScenarios":"The same collection property mapped through more than one channel: annotated class plus an overlapping hbm.xml; the same hbm resource added twice (duplicate addResource or duplicate <mapping resource=...>); the property mapped in both superclass and subclass XML; or programmatic addCollectionBinding reusing a role.","commonSituations":"Transitioning from XML to annotations without removing the old mapping; wildcard resource scanning that registers the same file twice; copy-pasted hbm fragments; merging modules that both map the same relation.","solutions":["Find the role named in the message (<Entity>.<property>) and remove the extra mapping, keeping exactly one","Check that the same resource is not added twice via MetadataSources.addResource or <mapping resource=...>","When mixing annotations and XML, map each property in only one of them","For programmatic metadata, guard with getCollectionBinding(role) != null before adding"],"exampleFix":"// before: same resource registered twice\nsources.addResource(\"com/acme/Order.hbm.xml\");\nsources.addResource(\"com/acme/Order.hbm.xml\");\n\n// after: register each mapping once\nSet<String> added = new HashSet<>();\nfor (String r : mappingResources) {\n    if (added.add(r)) sources.addResource(r);\n}","handlingStrategy":"try-catch","validationCode":"// Guard programmatic collection registration\nif (inFlightMetadata.getCollectionBinding(collection.getRole()) != null) {\n    LOG.warn(\"collection role already mapped, skipping: {}\", collection.getRole());\n    return;\n}\ninFlightMetadata.addCollectionBinding(collection);","typeGuard":null,"tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n}\ncatch (DuplicateMappingException e) {\n    // role string names the duplicated collection (Entity.property):\n    // remove the duplicate property mapping (annotations vs XML, or resource added twice)\n}","preventionTips":["When mixing annotations and XML, ensure the same property is mapped only once","Track added resources in a Set so the same hbm.xml is never registered twice"],"tags":["hibernate","collection-mapping","duplicate","hbm-xml"],"backgroundTag":"duplicate-collection-mapping","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}