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

Panache queries cannot mix range(int,int) with page-related methods. checkPagination() throws UnsupportedOperationException when a page method is invoked on a query whose result window was defined with range().

Source

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

        long count = count();
        if (count == 0)
            return 1; // a single page of zero results
        int pageSize = keyedPage != null ? keyedPage.getPage().getSize() : page.size;
        return (int) Math.ceil((double) count / (double) pageSize);
    }

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

    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;

View on GitHub (pinned to e1c734241f)

Solutions

Replace range(from, to) with page(pageIndex, pageSize) and use page-related methods.
Keep range() queries free of page methods; use list() to get results directly.
Create two separate queries if you need both a range window and paginated access.

Example fix

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

// after
PanacheQuery<Person> q = Person.find("status", "active").page(0, 50);
q.hasNextPage();

Defensive patterns

Strategy: validation

Validate before calling

if (query instanceof rangedQuery) { // don't call page methods on range queries
    throw new IllegalStateException("Use page() instead of range() to enable page methods");
}

Try / catch

try {
    q.hasNextPage();
} catch (UnsupportedOperationException e) {
    // re-create the query with .page(pageIndex, pageSize) instead of range()
}

Prevention

Pick range() or page() per query, never both.
Document that range() disables page-navigation methods.
Convert range windows to page(Page.of(from / size, size)) when page methods are needed.

When it happens

Trigger: Calling query.range(from, to) and then nextPage(), previousPage(), firstPage(), lastPage(), hasNextPage(), hasPreviousPage() or page() on the same query.

Common situations: Code that used range() for one-off windows later extended with paging logic; mixed pagination styles across refactors.

Related errors

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