hibernate/hibernate-orm · error · UnsupportedMappingException

NaturalIdClass not supported for simple naturaal-id mappings

Error message

NaturalIdClass not supported for simple naturaal-id mappings

What it means

Error "NaturalIdClass not supported for simple naturaal-id mappings" thrown in hibernate/hibernate-orm.

Source

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

			naturalIdMapping = generateNaturalIdMapping( creationProcess, bootEntityDescriptor );
		}
		else {
			naturalIdMapping = null;
		}
	}

	protected NaturalIdMapping generateNaturalIdMapping(
			MappingModelCreationProcess creationProcess,
			PersistentClass bootEntityDescriptor) {
		//noinspection AssertWithSideEffects
		assert bootEntityDescriptor.hasNaturalId();

		final int[] naturalIdAttributeIndexes = getNaturalIdentifierProperties();
		assert naturalIdAttributeIndexes.length > 0;

		if ( naturalIdAttributeIndexes.length == 1 ) {
			if ( bootEntityDescriptor.getRootClass().getNaturalIdClass() != null ) {
				throw new UnsupportedMappingException( "NaturalIdClass not supported for simple naturaal-id mappings" );
			}
			final String propertyName = getPropertyNames()[ naturalIdAttributeIndexes[ 0 ] ];
			final var attributeMapping = (SingularAttributeMapping) findAttributeMapping( propertyName );
			return new SimpleNaturalIdMapping(
					attributeMapping,
					this,
					creationProcess
			);
		}

		// 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

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @NaturalIdClass usage for a single-attribute natural id; annotate the attribute with @NaturalId directly.
2. Add a second natural-id attribute if a compound NaturalIdClass is intended.

When it happens

Trigger: Thrown when a NaturalIdClass is declared for an entity that has only a single (simple) natural-id attribute.

Common situations: See trigger scenarios.

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