hibernate/hibernate-orm · error · IllegalArgumentException

Incoming natural-id value [%s (`%s`)] is not of expected typ

Error message

Incoming natural-id value [%s (`%s`)] is not of expected type [`%s`] and could not be coerced

What it means

Error "Incoming natural-id value [%s (`%s`)] is not of expected type [`%s`] and could not be coerced" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/mapping/internal/SimpleNaturalIdMapping.java:125

	@Override
	public boolean isNormalized(Object incoming) {
		return incoming == null || getJavaType().getJavaTypeClass().isInstance( incoming );
	}

	@Override
	public void validateInternalForm(Object naturalIdValue) {
		if ( naturalIdValue != null ) {
			final var naturalIdValueClass = naturalIdValue.getClass();
			// be flexible - allow a single-valued array
			if ( naturalIdValueClass.isArray() && !naturalIdValueClass.getComponentType().isPrimitive() ) {
				final var values = (Object[]) naturalIdValue;
				if ( values.length == 1 ) {
					naturalIdValue = values[0];
				}
			}

			if ( !getJavaType().isInstance( naturalIdValue ) ) {
				throw new IllegalArgumentException(
						String.format(
								Locale.ROOT,
								"Incoming natural-id value [%s (`%s`)] is not of expected type [`%s`] and could not be coerced",
								naturalIdValue,
								naturalIdValueClass.getName(),
								getJavaType().getTypeName()
						)
				);
			}
		}
	}

	@Override
	public int calculateHashCode(Object value) {
		//noinspection rawtypes,unchecked
		return value == null ? 0 : ( (JavaType) getJavaType() ).extractHashCode( value );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass a natural-id value of the exact Java type of the natural-id attribute.
2. Ensure the value can be coerced (e.g. correct numeric/string form) to the natural-id attribute type.

When it happens

Trigger: Thrown when a natural-id value supplied for loading has a Java type that does not match the declared attribute type and cannot be coerced.

Common situations: See trigger scenarios.

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