quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a page related method in a ranged query, call pa

Error message

Cannot call a page related method in a ranged query, call page(Page) or page(int, int) to initiate pagination first

What it means

Thrown by CommonAbstractPanacheQueryImpl.checkPagination when a page-related method (nextPage, previousPage, firstPage, lastPage, hasNextPage, hasPreviousPage) is invoked on a Hibernate Reactive Panache query that was never paged, or that was configured with range(int,int) instead of page(). Panache requires pagination to be initialized before page navigation/inspection because the Page state is what those methods operate on. It is an UnsupportedOperationException, i.e. a programming/API-usage error, not a runtime environment failure.

Source

Thrown at extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/CommonAbstractPanacheQueryImpl.java:204

            if (count == 0)
                return 1; // a single page of zero results
            return (int) Math.ceil((double) count / (double) page.size);
        });
    }

    public Page page() {
        checkPagination();
        return page;
    }

    private void checkPagination() {
        // FIXME: turn into Uni
        if (page == 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");
        }
    }

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

    public void range(int startIndex, int lastIndex) {
        this.range = Range.of(startIndex, lastIndex);
        // reset the page to its default to be able to switch from page to range
        this.page = null;
    }

    private void checkRange() {
        if (range == null) {
            throw new UnsupportedOperationException("Cannot call a range related method, " +

View on GitHub (pinned to e1c734241f)

Solutions

1. Call page(int pageIndex, int pageSize) or page(Page) on the PanacheQuery before invoking any page-related method.
2. If you only want a bounded result set, use range(int startIndex, int lastIndex) and drop nextPage/previousPage calls entirely.
3. Remove range(...) calls if you intend to paginate; a query cannot be both paged and ranged.
4. Use list()/firstResult()/singleResult() instead if pagination helpers are not actually needed.

Example fix

// before
PanacheQuery<Person> q = Person.find("age > ?1", 18);
boolean more = q.hasNextPage(); // UnsupportedOperationException

// after
PanacheQuery<Person> q = Person.find("age > ?1", 18).page(0, 20);
boolean more = q.hasNextPage();

if (query.range() != null) { throw new IllegalStateException("Query is ranged; page methods unavailable"); }
// or track it: ensure you called .page(p, s) before hasNextPage()/nextPage()/firstPage()/lastPage()

try { more = query.hasNextPage(); } catch (UnsupportedOperationException e) { query.page(0, defaultSize); more = query.hasNextPage(); }

When it happens

Trigger: Calling nextPage()/previousPage()/firstPage()/lastPage()/hasNextPage()/hasPreviousPage() on a PanacheQuery created via find()/list()/query() without first calling page(Page) or page(int pageIndex, int pageSize); or after calling range(int,int), which puts the query in ranged mode (checkPagination throws when range != null).

Common situations: Developers assume a fresh query has an implicit default page (like JDBC-style offset/limit habits); code refactored from range() to pagination but still calling nextPage(); mixing page() and range() on the same query object.

Related errors

• Cannot call a page related method, call page(Page) or page(i
• Cannot call a range related method in a paged query, call ra
• Limiting to 0 values is not supported
• Cursor-based pagination is not supported by Hibernate Reacti
• Cannot navigate to last page in cursor-based pagination

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