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

This UnsupportedOperationException is thrown by checkPagination() in CommonReactivePanacheQueryImpl. Panache queries support two mutually exclusive result-limiting modes: paging (page(Page)/page(int,int)) and ranging (range(int,int)). Page-navigation methods (nextPage, previousPage, firstPage, lastPage, hasNextPage, hasPreviousPage) require the query to be in paging mode with no range set, so they throw when the query was created with range() or when no page was ever set.

Source

Thrown at extensions/panache/mongodb-panache-common/runtime/src/main/java/io/quarkus/mongodb/panache/common/reactive/runtime/CommonReactivePanacheQueryImpl.java:136

            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> CommonReactivePanacheQueryImpl<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 (CommonReactivePanacheQueryImpl<T>) this;
    }

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

    public <T extends Entity> CommonReactivePanacheQueryImpl<T> withReadPreference(ReadPreference readPreference) {
        this.collection = this.collection.withReadPreference(readPreference);

View on GitHub (pinned to e1c734241f)

Solutions

Remove the range(...) call and use page(Page) or page(pageIndex, size) before calling any page-related method
If you need ranged fetching, replace page-navigation calls with list()/firstResult() and re-issue queries with adjusted range indices
Split the logic: use range() for single-shot fetches, page() only when you need hasNextPage/nextPage navigation

Example fix

// before
var query = reactiveFind("status = ?1", "OPEN").range(0, 9);
boolean more = query.hasNextPage(); // throws

// after
var query = reactiveFind("status = ?1", "OPEN").page(0, 10);
boolean more = query.hasNextPage(); // works

Defensive patterns

Strategy: validation

Validate before calling

if (query.getClass().getSimpleName().contains("ReactivePanacheQuery")) {
    // ensure paging mode before navigation
    query.page(0, 20); // initialize page
    // do NOT call range(...) if you will use nextPage/hasNextPage
}

Try / catch

try {
    return query.hasNextPage();
} catch (UnsupportedOperationException e) {
    // query was ranged or paged never initialized; fall back to count + range
    return false;
}

Prevention

Pick one limiting mode per query: page() for navigation, range() for one-shot slices
Call page(Page) immediately after building the query if any page-related method may be used
Wrap pagination logic in a repository helper so page vs range is decided in one place

When it happens

Trigger: Calling nextPage(), previousPage(), firstPage(), lastPage(), hasNextPage(), or hasPreviousPage() on a query on which range(startIndex, lastIndex) was called, or on which no page(Page)/page(int,int) was called at all (page == null).

Common situations: Developers mixing paging and range APIs on the same query; calling hasNextPage() on a query built for a one-off range fetch; refactoring code from page() to range() while keeping page-navigation calls; copying query-building code that ends with range() but retains UI pagination logic.

Related errors

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