quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a page related method, call page(Page) or page(i

Error message

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

What it means

Page-related methods (nextPage, previousPage, firstPage, lastPage, hasNextPage, hasPreviousPage, page()) require that pagination was initiated with page(Page) or page(int, int). If neither page nor keyedPage was set, checkPagination() throws UnsupportedOperationException.

Source

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

    }

    public int pageCount() {
        checkPagination();
        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");
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

Call page(int pageIndex, int pageSize) before any page-related method.
Call page(Page.of(pageIndex, pageSize)) with a Page instance.
If the query uses range(int,int), switch to pagination — range and page are mutually exclusive.
Initialize Page.page() (first page) explicitly at query construction.

Example fix

// before
PanacheQuery<Person> q = Person.find("status", "active");
q.nextPage(); // throws

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

Defensive patterns

Strategy: validation

Validate before calling

PanacheQuery<Person> q = Person.find("active");
if (!q.page() initialized) { // call page() first
    q.page(0, 20);
}
q.nextPage();

Try / catch

try {
    q.nextPage();
} catch (UnsupportedOperationException e) {
    q.page(Page.of(0, defaultPageSize));
    q.nextPage();
}

Prevention

Always initialize pagination with page(0, size) right after find().
Centralize query construction so page() is never skipped.
Remember range() and page() are mutually exclusive.

When it happens

Trigger: Calling nextPage()/firstPage()/hasNextPage()/etc. on a PanacheQuery on which page(Page) or page(int, int) was never called.

Common situations: Forgetting to set an initial page on a repository finder; conditionally applying pagination in code paths where it was skipped.

Related errors

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