quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a range related method in a paged query, call ra

Error message

Cannot call a range related method in a paged query, call range(int, int) to initiate range first

What it means

Panache queries cannot mix pagination with range access. checkRange() throws UnsupportedOperationException when range-related methods are used on a query that was paginated with page(Page) or page(int, int).

Source

Thrown at extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/CommonPanacheQueryImpl.java:302

    private void checkPagination() {
        if (page == null && keyedPage == null) {
            throw new UnsupportedOperationException("Cannot call a page related method, " +
                    "call page(Page) or page(int, int) to initiate pagination first");
        }
        if (range != null) {
            throw new UnsupportedOperationException("Cannot call a page related method in a ranged query, " +
                    "call page(Page) or page(int, int) to initiate pagination first");
        }
    }

    private void checkRange() {
        if (range == null) {
            throw new UnsupportedOperationException("Cannot call a range related method, " +
                    "call range(int, int) to initiate range first");
        }
        if (page != null) {
            throw new UnsupportedOperationException("Cannot call a range related method in a paged query, " +
                    "call range(int, int) to initiate range first");
        }
    }

    public Range range() {
        checkRange();
        return range;
    }

    public void range(int startIndex, int lastIndex) {
        this.range = Range.of(startIndex, lastIndex);
        this.page = null;
        this.keyedPage = null;
        this.lastKeyedResult = null;
    }

    public void withLock(LockModeType lockModeType) {
        this.lockModeType = lockModeType;

View on GitHub (pinned to e1c734241f)

Solutions

Choose one model: use page(pageIndex, pageSize) for paging or range(from, to) for a fixed window, not both.
Replace the range call with page(Page.of(0, size)) if you need a first-window equivalent.
Build a separate query instance when both windows are needed.

Example fix

// before
PanacheQuery<Person> q = Person.find("status", "active").page(0, 20);
q.range(0, 49); // throws

// after
PanacheQuery<Person> q = Person.find("status", "active").range(0, 49); // window instead of page
// or: .page(0, 20) and use page methods

Defensive patterns

Strategy: validation

Validate before calling

if (queryWasPaged) {
    throw new IllegalStateException("Do not call range() on a paged query; use page methods");
}

Try / catch

try {
    q.range(0, 49);
} catch (UnsupportedOperationException e) {
    // recreate query with range() only, or use page(Page.of(0, 50))
}

Prevention

Enforce a single windowing style per query instance.
Do not apply generic range() utilities to queries already built with page().
Prefer page(Page.of(...)) since it also supports page navigation.

When it happens

Trigger: Calling query.page(...) and then range() accessor or range(int,int) on the same query.

Common situations: Mixing pagination and range code paths; utilities that unconditionally apply range() to a query that was already paged.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/309d17c451c6abae. Report an issue: GitHub.