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 navigation methods (nextPage, previousPage, firstPage, lastPage, hasNextPage, hasPreviousPage) on a PanacheQuery require that pagination was explicitly initialized with page(Page) or page(int,int). If query.page() was never called and the internal page field is null, checkPagination() throws this UnsupportedOperationException.

Source

Thrown at extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/runtime/CommonPanacheQueryImpl.java:131

        return page.index > 0;
    }

    public int pageCount() {
        checkPagination();
        long count = count();
        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() {
        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 <T extends Entity> CommonPanacheQueryImpl<T> 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;
        return (CommonPanacheQueryImpl<T>) this;
    }

    public <T extends Entity> CommonPanacheQueryImpl<T> withCollation(Collation collation) {
        this.collation = collation;

View on GitHub (pinned to e1c734241f)

Solutions

Call page(int pageSize) or page(int pageIndex, int pageSize) on the query before any page-related method
Pass a Page object: query.page(Page.of(pageIndex, pageSize))
If you only need slicing without paging semantics, use range(startIndex, lastIndex) instead and avoid page methods

Example fix

// before
PanacheQuery<Person> query = Person.find("status", "active");
boolean more = query.hasNextPage();

// after
PanacheQuery<Person> query = Person.find("status", "active").page(1, 20);
boolean more = query.hasNextPage();

Defensive patterns

Strategy: validation

Validate before calling

if (query.page() == null) { // UnsupportedOperationException otherwise
    query.page(1, 20);
}

Try / catch

try {
    boolean more = query.hasNextPage();
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("initiate pagination first")) {
        query.page(1, 20); // recover by initializing pagination
    } else { throw e; }
}

Prevention

Always call .page(pageIndex, pageSize) immediately after find()/findAll() when using queries
Wrap query creation in a helper/factory that guarantees pagination is initialized
Never call hasNextPage()/nextPage() on range()-based queries
Add unit tests for paginated repository methods so the failure surfaces in CI

When it happens

Trigger: Calling any of nextPage(), previousPage(), firstPage(), lastPage(), hasNextPage(), hasPreviousPage() directly on a PanacheQuery created by find()/list()/findAll() without first calling page(size) or page(index,size).

Common situations: Developers assuming Panache queries are paginated by default; migrating code that previously called page() upstream and forgetting it after refactoring; reading pagination state before initiating pagination.

Related errors

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