quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a range related method in a paged query, call…

Error message

Cannot call a range related method in a paged query, call range(int, int) to initiate range first

What it means

Thrown by CommonAbstractPanacheQueryImpl.checkRange when a range-related method is called on a query that is in paged mode (page != null). Panache queries support either pagination (page(Page)) or a fixed range (range(int,int)), never both at once; switching from page to range resets the page, but the reverse mix triggers this error. It is an UnsupportedOperationException for incompatible query configuration.

Solutions

Remove the page(...) call so the query is not in paged mode before applying range(int,int).
Choose one mode: use page(int,int) + page accessors for pagination, or range(int,int) alone for a one-shot window.
Use a fresh PanacheQuery instance for the ranged variant instead of reusing a paged one.

Example fix

// before
PanacheQuery<Person> q = Person.find("age > ?1", 18).page(0, 20);
q.range(0, 50); // UnsupportedOperationException

// after
PanacheQuery<Person> q = Person.find("age > ?1", 18).range(0, 50);

Defensive patterns

Strategy: validation

Validate before calling

if (isPaged(query)) { throw new IllegalStateException("Cannot apply range to a paged query"); } // keep a boolean when you call .page(...)

Try / catch

try { query.range(start, end); } catch (UnsupportedOperationException e) { query = baseQuery().range(start, end); }

Prevention

One mode per query: choose page() or range() at construction time
Create a fresh PanacheQuery from the base find()/query() when switching modes
Encapsulate paging vs ranging in repository helpers so callers cannot mix them

When it happens

Trigger: Calling range(int,int) (or range accessor) on a PanacheQuery on which page(Page) or page(int,int) was previously called without any way to have cleared paging state; interleaving paging and ranging helpers on the same query object.

Common situations: Refactored code that switched a query from page() to range() but left page-related calls in place, or utility code that applies range() to a query already configured by a caller with page().

Related errors

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

Appendix: source

Thrown at extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/CommonAbstractPanacheQueryImpl.java:226

    public Range range() {
        checkRange();
        return range;
    }

    public void 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;
    }

    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");
        }
    }

    public void withLock(LockModeType lockModeType) {
        this.lockModeType = lockModeType;
    }

    public void withHint(String hintName, Object value) {
        if (hints == null) {
            hints = new HashMap<>();
        }
        hints.put(hintName, value);
        throw new UnsupportedOperationException("Hints not supported yet");
    }

    // Results

View on GitHub (pinned to e1c734241f)