hibernate/hibernate-orm · error · UnsupportedMappingException

Could not normalize compound natural id value: %s

Error message

Could not normalize compound natural id value: %s

What it means

Error "Could not normalize compound natural id value: %s" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/mapping/internal/CompoundNaturalIdMapping.java:752

		return new KeyClassNormalizer( keyAttributes, naturalIdClass, attributeMappers );
	}

	static class ValueNormalizerSupport implements ValueNormalizer {
		private final List<SingularAttributeMapping> naturalIdAttributes;

		public ValueNormalizerSupport(List<SingularAttributeMapping> naturalIdAttributes) {
			this.naturalIdAttributes = naturalIdAttributes;
		}

		@Override
		public boolean isInstance(Object value) {
			return value instanceof Map;
		}

		@Override
		public Object[] normalize(Object incoming) {
			if ( !isInstance( incoming ) ) {
				throw new UnsupportedMappingException( "Could not normalize compound natural id value: " + incoming );
			}
			final var values = new Object[naturalIdAttributes.size()];
			//noinspection unchecked
			final Map<String,Object> valuesMap = (Map<String,Object>) incoming;
			for ( int i = 0; i < naturalIdAttributes.size(); i++ ) {
				values[i] = valuesMap.get( naturalIdAttributes.get( i ).getAttributeName() );
			}
			return values;
		}

		@Override
		public Class<?> getIdClassType() {
			return null;
		}
	}

	/// Responsible for decomposing a value of the NaturalIdClass into the internal array format
	static class KeyClassNormalizer<T> extends ValueNormalizerSupport {

View on GitHub (pinned to fad1729dce)

Solutions

1. Check the natural-id attribute values for nulls or types that cannot be normalized; supply a complete, correctly-typed natural id value.

When it happens

Trigger: Thrown when a compound natural id value (map or array) cannot be normalized into the internal per-attribute representation.

Common situations: See trigger scenarios.

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