hibernate/hibernate-orm · error · DuplicateMappingException

Duplicate collection definition '%s'

Error message

Duplicate collection definition '%s'

What it means

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.

Source

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

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

	@Override
	public java.util.Collection<Collection> getCollectionBindings() {
		return collectionBindingMap.values();
	}

	@Override
	public Collection getCollectionBinding(String role) {
		return collectionBindingMap.get( role );
	}

	@Override
	public void addCollectionBinding(Collection collection) throws DuplicateMappingException {
		final String collectionRole = collection.getRole();
		if ( collectionBindingMap.containsKey( collectionRole ) ) {
			throw new DuplicateMappingException( DuplicateMappingException.Type.COLLECTION, collectionRole );
		}
		collectionBindingMap.put( collectionRole, collection );
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Hibernate Type handling


	@Override
	public TypeDefinitionRegistry getTypeDefinitionRegistry() {
		return typeDefRegistry;
	}

	@Override
	public TypeDefinition getTypeDefinition(String registrationKey) {
		return typeDefRegistry.resolve( registrationKey );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Find the role named in the message (<Entity>.<property>) and remove the extra mapping, keeping exactly one
2. Check that the same resource is not added twice via MetadataSources.addResource or <mapping resource=...>
3. When mixing annotations and XML, map each property in only one of them
4. For programmatic metadata, guard with getCollectionBinding(role) != null before adding

Example fix

// before: same resource registered twice
sources.addResource("com/acme/Order.hbm.xml");
sources.addResource("com/acme/Order.hbm.xml");

// after: register each mapping once
Set<String> added = new HashSet<>();
for (String r : mappingResources) {
    if (added.add(r)) sources.addResource(r);
}

// Guard programmatic collection registration
if (inFlightMetadata.getCollectionBinding(collection.getRole()) != null) {
    LOG.warn("collection role already mapped, skipping: {}", collection.getRole());
    return;
}
inFlightMetadata.addCollectionBinding(collection);

try {
    metadata.buildSessionFactory();
}
catch (DuplicateMappingException e) {
    // role string names the duplicated collection (Entity.property):
    // remove the duplicate property mapping (annotations vs XML, or resource added twice)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unexpected node type -
• Duplicate entity definition '%s'
• Entity classes [%s] and [%s] share the entity name '%s' (ent
• Duplicate generator name '%s'; you will likely want to set t
• Duplicate named entity graph '%s'

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