hibernate/hibernate-orm · error · IllegalArgumentException

Key definition must not be empty or null

Error message

Key definition must not be empty or null

What it means

Error "Key definition must not be empty or null" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/Page.java:165

	public <R> KeyedPage<R> keyedBy(Order<? super R> keyDefinition) {
		if ( keyDefinition == null )  {
			throw new IllegalArgumentException("Key definition must not null");
		}
		return new KeyedPage<>( List.of(keyDefinition), this );
	}

	/**
	 * Obtain a {@linkplain KeyedPage key-based specification} of this page.
	 *
	 * @param keyDefinition a list of {@link Order} objects defining a total
	 *                      order on the result set
	 * @return a {@link KeyedPage} representing this page
	 *
	 * @since 6.5
	 */
	public <R> KeyedPage<R> keyedBy(List<Order<? super R>> keyDefinition) {
		if ( keyDefinition == null || keyDefinition.isEmpty() )  {
			throw new IllegalArgumentException("Key definition must not be empty or null");
		}
		return new KeyedPage<>( keyDefinition, this );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Provide a non-empty key definition list for keyset pagination.
2. Ensure at least one ordering key is supplied.

When it happens

Trigger: A runtime precondition of the Hibernate API is violated.

Common situations: Occurs when application code or configuration does not satisfy the documented contract of the API being called.

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