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

The hibernate.order_by.default_null_ordering setting is parsed with NullsHelper.parse, which matches the String (case-insensitively) against the jakarta.persistence.criteria.Nulls enum values: none, first, last. An unrecognized String yields null from the parser and SessionFactoryOptionsBuilder throws IllegalArgumentException, aborting SessionFactory bootstrap.

Source

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

		}
		else if ( jdbcTimeZoneValue != null ) {
			throw new IllegalArgumentException( "Configuration property " + JDBC_TIME_ZONE
												+ " value [" + jdbcTimeZoneValue + "] is not supported" );
		}
		else {
			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?

View on GitHub (pinned to fad1729dce)

Solutions

1. Use exactly one of: none, first, last (case-insensitive)
2. Or pass the typed value directly: props.put("hibernate.order_by.default_null_ordering", Nulls.FIRST) with jakarta.persistence.criteria.Nulls
3. Trim values sourced from environment variables or YAML before setting them
4. Remove the property entirely — the default is Nulls.NONE

Example fix

# before:
hibernate.order_by.default_null_ordering = nulls_first

# after:
hibernate.order_by.default_null_ordering = first

// validate before boot
static boolean isValidNullOrdering(String s) {
    if (s == null) return true;
    return Arrays.stream(Nulls.values()).anyMatch(n -> n.name().equalsIgnoreCase(s.trim()));
}

if (!isValidNullOrdering(props.getProperty("hibernate.order_by.default_null_ordering")))
    throw new IllegalArgumentException("Use none, first, or last");

static String sanitizeNullOrdering(String raw) {
    if (raw == null) return null;
    String v = raw.trim().toLowerCase(Locale.ROOT);
    return switch (v) { case "none", "first", "last" -> v; default -> null; };
}

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

When it happens

Trigger: Setting hibernate.order_by.default_null_ordering to any string other than none/first/last (case-insensitive), e.g. 'nulls_first', 'high', 'smallest', 'asc_nulls_first', or a value with surrounding whitespace.

Common situations: Porting PostgreSQL/Oracle hint vocabulary ('NULLS FIRST') into the property; using values from SQL ORDER BY clauses or other ORMs; whitespace from a YAML/ENV-injected value; downgrading knowledge from docs listing different keywords.

Related errors

• Configuration property hibernate.order_by.default_null_order
• The {storageEngine} storage engine is not supported
• Audit graph mutation plan used with non-graph action queue
• Audit graph mutation plan used with non-graph action queue
• Unknown ActionQueue implementation: %s. Valid values are 'gr

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