hibernate/hibernate-orm · error · MappingException

Expected multiple natural-id attributes, but found only one:

Error message

Expected multiple natural-id attributes, but found only one: ${entityName}

What it means

Error "Expected multiple natural-id attributes, but found only one: ${entityName}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/AbstractEntityPersister.java:5663

		// collect the names of the attributes making up the natural-id.
		final Set<String> attributeNames = setOfSize( naturalIdAttributeIndexes.length );
		for ( int naturalIdAttributeIndex : naturalIdAttributeIndexes ) {
			attributeNames.add( getPropertyNames()[ naturalIdAttributeIndex ] );
		}

		// then iterate over the attribute mappings finding the ones having names
		// in the collected names.  iterate here because it is already alphabetical

		final List<SingularAttributeMapping> collectedAttrMappings = new ArrayList<>();
		for ( int i = 0; i < attributeMappings.size(); i++ ) {
			final var attributeMapping = attributeMappings.get( i );
			if ( attributeNames.contains( attributeMapping.getAttributeName() ) ) {
				collectedAttrMappings.add( (SingularAttributeMapping) attributeMapping );
			}
		}

		if ( collectedAttrMappings.size() <= 1 ) {
			throw new MappingException( "Expected multiple natural-id attributes, but found only one: " + getEntityName() );
		}

		return new CompoundNaturalIdMapping(
				this,
				bootEntityDescriptor.getRootClass().getNaturalIdClass(),
				collectedAttrMappings,
				creationProcess
		);
	}

	protected static SqmMultiTableMutationStrategy interpretSqmMultiTableStrategy(
			AbstractEntityPersister entityMappingDescriptor,
			MappingModelCreationProcess creationProcess) {
		assert entityMappingDescriptor.hasMultipleTables();
		final var superMappingType = entityMappingDescriptor.getSuperMappingType();
		if ( superMappingType != null ) {
			final var sqmMultiTableMutationStrategy =
					superMappingType.getSqmMultiTableMutationStrategy();

View on GitHub (pinned to fad1729dce)

Solutions

1. Annotate all attributes comprising the compound natural id with @NaturalId, or remove @NaturalIdClass if only one attribute forms the natural id.

When it happens

Trigger: Thrown when a compound natural id mapping is expected but the entity declares only one natural-id attribute.

Common situations: See trigger scenarios.

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