hibernate/hibernate-orm · error · IllegalArgumentException

Configuration property hibernate.order_by.default_null_order

Error message

Configuration property hibernate.order_by.default_null_ordering value [{}] is not recognized

What it means

When hibernate.order_by.default_null_ordering holds a non-null value that is neither a jakarta.persistence.criteria.Nulls enum nor a String, SessionFactoryOptionsBuilder throws IllegalArgumentException at bootstrap. The message uses square brackets to signal the failure is about the value's type, not its textual content.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/SessionFactoryOptionsBuilder.java:652

			return null;
		}
	}

	@Nonnull
	private Nulls getDefaultNullPrecedence(Object defaultNullPrecedence) {
		if ( defaultNullPrecedence instanceof Nulls jpaValue ) {
			return jpaValue;
		}
		else if ( defaultNullPrecedence instanceof String string ) {
			final var parsed = NullsHelper.parse( string );
			if ( parsed == null ) {
				throw new IllegalArgumentException( "Configuration property " + DEFAULT_NULL_ORDERING
													+ " value '" + defaultNullPrecedence + "' is not recognized" );
			}
			return parsed;
		}
		else if ( defaultNullPrecedence != null ) {
			throw new IllegalArgumentException( "Configuration property " + DEFAULT_NULL_ORDERING
												+ " value [" + defaultNullPrecedence + "] is not recognized" );
		}
		else {
			return Nulls.NONE;
		}
	}

	@Nullable
	private static Class<? extends SessionEventListener> getAutoSessionEventsListener(
			Map<String, Object> configurationSettings,
			StrategySelector strategySelector) {
		// todo : expose this from builder?
		final String name = (String) configurationSettings.get( AUTO_SESSION_EVENTS_LISTENER );
		return name == null ? null : strategySelector.selectStrategyImplementor( SessionEventListener.class, name );
	}

	private static boolean disallowBatchUpdates(Dialect dialect, ExtractedDatabaseMetaData meta) {
		final Boolean dialectAnswer = dialect.supportsBatchUpdates();

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass a jakarta.persistence.criteria.Nulls enum value (Nulls.NONE, Nulls.FIRST, Nulls.LAST)
2. Or pass the equivalent String 'none'/'first'/'last'
3. After a Hibernate upgrade, replace removed enum types like org.hibernate.NullPrecedence with Nulls
4. Set the value through typed APIs (e.g. SessionFactoryBuilder) rather than raw maps when possible

Example fix

// before (old Hibernate 6 enum, removed later):
props.put("hibernate.order_by.default_null_ordering", org.hibernate.NullPrecedence.FIRST);

// after:
props.put("hibernate.order_by.default_null_ordering", jakarta.persistence.criteria.Nulls.FIRST);

// ensure the property value is Nulls or String before boot
Object v = props.get("hibernate.order_by.default_null_ordering");
if (v != null && !(v instanceof Nulls) && !(v instanceof String))
    throw new IllegalArgumentException(
        "hibernate.order_by.default_null_ordering must be Nulls or String, got " + v.getClass());

static boolean isSupportedNullOrderingValue(Object v) {
    return v == null || v instanceof jakarta.persistence.criteria.Nulls || v instanceof String;
}

try {
    sessionFactory = configuration.buildSessionFactory();
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("default_null_ordering")) {
        props.put("hibernate.order_by.default_null_ordering", Nulls.NONE); // typed known-good value
    } else throw e;
}

When it happens

Trigger: Putting an Integer (e.g. 1), Boolean, or an enum of a different type (such as the pre-Hibernate-7 org.hibernate.NullPrecedence or a custom enum) into hibernate.order_by.default_null_ordering.

Common situations: Upgrading Hibernate where code passed the old NullPrecedence enum that was replaced by Nulls; Spring/type-safe configuration binding an int constant; copy-pasting values between settings blocks of different types.

Related errors

• Configuration property hibernate.order_by.default_null_order
• jakarta.persistence.validation.group.{} is of unknown type:
• Configuration property hibernate.jdbc.time_zone value [{}] i
• Could not determine how to handle configuration raw [name=${
• Could not determine how to handle configuration value [name=

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