quarkusio/quarkus · error · UnsupportedOperationException

Cannot call nextPage() before fetching results with list()

Error message

Cannot call nextPage() before fetching results with list()

What it means

In keyed (cursor) pagination, next-page keys come from the last fetched KeyedResult. Calling nextPage() before any results were fetched via list() means there is no key to advance from, so Panache throws UnsupportedOperationException.

Solutions

Call .list() (or .firstResult()) first, then nextPage()
Reorder the loop: fetch results, process, then call nextPage() for the next iteration
Use offset pagination (page()) if you don't need keyset semantics, since page.next() works without a prior fetch

Example fix

// before
query.cursor(0, 20).nextPage();
// after
List<Person> results = query.cursor(0, 20).list();
query.nextPage();

Defensive patterns

Strategy: try-catch

Try / catch

try {
    query.nextPage();
} catch (UnsupportedOperationException e) {
    if (e.getMessage() != null && e.getMessage().contains("before fetching results")) {
        query.list(); // fetch first, then advance
        query.nextPage();
    } else throw e;
}

Prevention

Always call list() before nextPage() on a keyed query
Structure page loops as: fetch, process, advance
Track cursor state explicitly when paginating across requests

When it happens

Trigger: Calling query.cursor(...).nextPage() immediately after pagination setup, before .list() has produced lastKeyedResult.

Common situations: Iterating pages in a loop where nextPage() is called at loop start instead of after fetching; misunderstanding the cursor API order (list first, then advance).

Related errors

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

Appendix: source

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

    @SuppressWarnings("unchecked")
    public void cursor(int pageIndex, int pageSize) {
        if (sort == null || sort.getColumns().isEmpty()) {
            throw new UnsupportedOperationException(
                    "Cannot use cursor-based pagination without sort criteria: use find(entityClass, query, sort) or findAll(entityClass, sort)");
        }
        List orders = PanacheJpaUtil.toHibernateOrders(entityClass, sort);
        this.keyedPage = org.hibernate.query.Page.page(pageSize, pageIndex).keyedBy(orders);
        this.lastKeyedResult = null;
        this.page = null;
        this.range = null;
    }

    public void nextPage() {
        checkPagination();
        if (keyedPage != null) {
            if (lastKeyedResult == null) {
                throw new UnsupportedOperationException(
                        "Cannot call nextPage() before fetching results with list()");
            }
            keyedPage = lastKeyedResult.getNextPage();
            lastKeyedResult = null;
        } else {
            page(page.next());
        }
    }

    public void previousPage() {
        checkPagination();
        if (keyedPage != null) {
            if (lastKeyedResult == null) {
                throw new UnsupportedOperationException(
                        "Cannot call previousPage() before fetching results with list()");
            }
            KeyedPage<?> prev = lastKeyedResult.getPreviousPage();
            if (prev != null) {

View on GitHub (pinned to e1c734241f)