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

A query that was given an explicit range via range(startIndex, lastIndex) cannot use page navigation methods; Panache models paging and ranging as mutually exclusive slice modes. checkPagination() throws this UnsupportedOperationException when range is set, telling you to switch to page-based pagination first.

Source

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

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

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

View on GitHub (pinned to e1c734241f)

Solutions

Replace range(...) with page(pageIndex, pageSize) (or page(Page.of(...))) before calling page-related methods
Remove the page-related method calls when using range-based slicing; compute boundaries manually
Restructure the code so a query uses either pagination or ranging, not both

Example fix

// before
PanacheQuery<Person> q = Person.findAll().range(0, 19);
boolean more = q.hasNextPage();

// after
PanacheQuery<Person> q = Person.findAll().page(0, 20);
boolean more = q.hasNextPage();

Defensive patterns

Strategy: validation

Validate before calling

if (query.range() != null) {
    throw new IllegalStateException("Use page(...) instead of range(...) with page-related methods");
}

Try / catch

try {
    boolean more = query.hasNextPage();
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("ranged query")) {
        throw new IllegalStateException("Switch this query from range(...) to page(...) to use paging", e);
    }
    throw e;
}

Prevention

Pick one slicing mode per query: either range(start,last) or page(i,size), never both
Audit helpers that call hasNextPage()/nextPage() so they only accept paged queries
Document in repository interfaces whether methods return paged or ranged queries
Prefer page-based APIs when the caller needs navigation; reserve range for fixed windows

When it happens

Trigger: Calling range(a,b) on a PanacheQuery and then invoking nextPage(), previousPage(), firstPage(), lastPage(), hasNextPage(), or hasPreviousPage() on it.

Common situations: Code that mixes windowed fetching (range) with later pagination logic; refactors where a previously paged query was switched to range for a one-off slice but downstream paging calls were left in place; utility helpers that always call hasNextPage after fetching.

Related errors

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