hibernate/hibernate-orm · error · IllegalStateException

NaturalIdClass#value must not be void.class

Error message

NaturalIdClass#value must not be void.class

What it means

Error "NaturalIdClass#value must not be void.class" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java:1866

		}
		// as a special favor to users, we allow @SQLRestriction to be declared on a @MappedSuperclass
		ClassDetails classToCheck = classDetails.getSuperClass();
		while ( classToCheck != null
				&& classToCheck.hasAnnotationUsage( MappedSuperclass.class, modelsContext ) ) {
			final var fromSuper = getOverridableAnnotation( classToCheck, SQLRestriction.class, context );
			if ( fromSuper != null ) {
				return fromSuper;
			}
			classToCheck = classToCheck.getSuperClass();
		}
		return null;
	}

	private void bindNaturalIdClass() {
		final var ann = annotatedClass.getAnnotationUsage( NaturalIdClass.class, modelsContext() );
		if ( ann != null ) {
			if ( ann.value() == void.class ) {
				throw new IllegalStateException( "NaturalIdClass#value must not be void.class" );
			}
			naturalIdClass =
					context.getBootstrapContext().getModelsContext()
							.getClassDetailsRegistry()
							.resolveClassDetails( ann.value().getName() );
		}
	}

	private void bindNaturalIdCache() {
		final var naturalIdCache = annotatedClass.getAnnotationUsage( NaturalIdCache.class, modelsContext() );
		if ( naturalIdCache != null ) {
			final String region = naturalIdCache.region();
			if ( region.isBlank() ) {
				final var explicitCache = annotatedClass.getAnnotationUsage( Cache.class, modelsContext() );
				naturalIdCacheRegion =
						explicitCache != null && isNotBlank( explicitCache.region() )
								? explicitCache.region() + NATURAL_ID_CACHE_SUFFIX
								: annotatedClass.getName() + NATURAL_ID_CACHE_SUFFIX;

View on GitHub (pinned to fad1729dce)

Solutions

1. Set NaturalIdClass#value to a concrete class instead of void.class.

When it happens

Trigger: A @NaturalId mapping is invalid (void NaturalIdClass value or misplaced @NaturalId).

Common situations: NaturalIdClass left at its default void.class, or @NaturalId declared on a subclass property.

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