hibernate/hibernate-orm · error · IllegalArgumentException

Natural-id value [{naturalIdValue}] did not contain the expe

Error message

Natural-id value [{naturalIdValue}] did not contain the expected number of elements [{attributes.size()}]

What it means

Error "Natural-id value [{naturalIdValue}] did not contain the expected number of elements [{attributes.size()}]" thrown in hibernate/hibernate-orm.

Source

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

			return array;
		}
		else {
			return valueNormalizer.normalize( incoming );
		}
	}

	@Override
	public boolean isNormalized(Object incoming) {
		return incoming instanceof Object[];
	}

	@Override
	public void validateInternalForm(Object naturalIdValue) {
		if ( naturalIdValue != null ) {
			// should be an array, with a size equal to the number of attributes making up this compound natural-id
			if ( naturalIdValue instanceof Object[] values ) {
				if ( values.length != attributes.size() ) {
					throw new IllegalArgumentException(
							"Natural-id value [" + naturalIdValue + "] did not contain the expected number of elements ["
							+ attributes.size() + "]"
					);
				}
			}
			else {
				throw new IllegalArgumentException(
						"Natural-id value [" + naturalIdValue + "] was not an array as expected" );
			}
		}
	}

	@Override
	public int calculateHashCode(Object value) {
		if ( value == null ) {
			return 0;
		}
		else {

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass a natural-id value array whose size equals the number of attributes of the compound natural id.
2. Use the natural-id access API (Session.byNaturalId with using()) instead of hand-built arrays.

When it happens

Trigger: Thrown when a compound natural-id value array has fewer or more elements than the entity's declared natural-id attributes.

Common situations: See trigger scenarios.

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