hibernate/hibernate-orm · error · IllegalArgumentException

Illegal null-value semantic: {nullValueSemantic}

Error message

Illegal null-value semantic: {nullValueSemantic}

What it means

Error "Illegal null-value semantic: {nullValueSemantic}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/internal/UnsavedValueFactory.java:86

	 * is not specified, determine the unsaved value by instantiating an instance of the
	 * entity and reading the value of its version property, or if that is not possible,
	 * using the java default value for the type.
	 */
	public static <T> VersionValue getUnsavedVersionValue(
			KeyValue bootVersionMapping,
			VersionJavaType<T> versionJavaType,
			Getter getter,
			Supplier<?> templateInstanceAccess) {
		final var nullValueSemantic = bootVersionMapping.getNullValueSemantic();
		return nullValueSemantic == null
				? inferUnsavedVersionValue( getter, templateInstanceAccess )
				: switch ( nullValueSemantic ) {
					case UNDEFINED -> VersionValue.UNDEFINED;
					case NULL -> VersionValue.NULL;
					case NEGATIVE -> VersionValue.NEGATIVE;
					// this should not happen since the DTD prevents it
					case VALUE -> new VersionValue( versionJavaType.fromString( bootVersionMapping.getNullValue() ) );
					default -> throw new IllegalArgumentException( "Illegal null-value semantic: " + nullValueSemantic );
				};
	}

	private static VersionValue inferUnsavedVersionValue(Getter getter, Supplier<?> templateInstanceAccess) {
		if ( getter != null && templateInstanceAccess != null ) {
			final Object defaultValue = getter.get( templateInstanceAccess.get() );
			// if the version of a newly instantiated object is null
			// or a negative number, use that value as the unsaved-value,
			// otherwise assume it's the initial version set by program
			return isNullInitialVersion( defaultValue )
					? new VersionValue( defaultValue )
					: VersionValue.UNDEFINED;
		}
		else {
			return VersionValue.UNDEFINED;
		}
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use a valid null-value semantic (e.g. NULL, UNDEFINED) supported by UnsavedValueFactory
2. Correct the unsaved-value configuration on the identifier mapping

When it happens

Trigger: Thrown at hibernate-core/src/main/java/org/hibernate/engine/internal/UnsavedValueFactory.java:86 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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