What causes "The required offset is beyond page capacity" in hibernate/hibernate-orm?

Pass toPageOffset(absoluteIndex) as the offset, never the absolute index

hibernate/hibernate-orm · error · IllegalArgumentException

The required offset is beyond page capacity

Error message

The required offset is beyond page capacity

What it means

AbstractPagedArray stores elements in fixed-size Page objects; Page.set(offset, element) hard-rejects any offset >= PAGE_CAPACITY with IllegalArgumentException. This is an internal invariant guard: callers are expected to translate an absolute index into (page, pageOffset) via toPageOffset(index). Seeing it means offset math in the calling code is wrong (e.g. an absolute index was passed where a within-page offset was expected).

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/util/collections/AbstractPagedArray.java:54

		/**
		 * Clears the contents of the page.
		 */
		public void clear() {
			// We need to null out everything to prevent GC nepotism (see https://hibernate.atlassian.net/browse/HHH-19047)
			Arrays.fill( elements, 0, lastNotEmptyOffset + 1, null );
			lastNotEmptyOffset = -1;
		}

		/**
		 * Set the provided element at the specified offset.
		 *
		 * @param offset the offset in the page where to set the element
		 * @param element the element to set
		 * @return the previous element at {@code offset} if one existed, or {@code null}
		 */
		public E set(int offset, Object element) {
			if ( offset >= PAGE_CAPACITY ) {
				throw new IllegalArgumentException( "The required offset is beyond page capacity" );
			}
			final Object old = elements[offset];
			if ( element != null ) {
				if ( offset > lastNotEmptyOffset ) {
					lastNotEmptyOffset = offset;
				}
			}
			else if ( lastNotEmptyOffset == offset && old != null ) {
				// must search backward for the first not empty offset
				int i = offset;
				for ( ; i >= 0; i-- ) {
					if ( elements[i] != null ) {
						break;
					}
				}
				lastNotEmptyOffset = i;
			}
			elements[offset] = element;

View on GitHub (pinned to fad1729dce)

Solutions

Pass toPageOffset(absoluteIndex) as the offset, never the absolute index
Add an assertion offset < PAGE_CAPACITY next to every page.set call during development
Write a unit test that fills past one page boundary (index == PAGE_CAPACITY) to catch paging math early

Example fix

// before: absolute index leaks into the page call
page.set( index, element );
// after: translate to within-page offset first
final Page<E> page = getOrCreatePage( index );
page.set( toPageOffset( index ), element );

Defensive patterns

Strategy: validation

Validate before calling

// Always derive the page offset; never pass absolute indexes to a Page
int pageOffset = toPageOffset( absoluteIndex );
assert pageOffset >= 0 && pageOffset < PAGE_CAPACITY;
page.set( pageOffset, element );

Prevention

Never call Page.set/get directly with absolute indexes — go through the AbstractPagedArray API that does the math
When subclassing, re-use toPageOffset/getPage rather than reimplementing paging arithmetic
Unit-test crossing page boundaries whenever you touch this code

When it happens

Trigger: Subclassing AbstractPagedArray (InstanceIdentityMap and InstanceIdentityStore do) and calling page.set(...) with an absolute index instead of toPageOffset(index); or computing page offsets with a different page size assumption than PAGE_CAPACITY.

Common situations: Almost never seen by Hibernate users — it guards internal persistence-context storage. It appears when extending or copying the paged-array code and getting the paging arithmetic wrong, typically off-by-PAGE_CAPACITY errors.

Related errors

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