quarkusio/quarkus · error · UnsupportedOperationException

Cannot call a range related method, call range(int, int) to

Error message

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

What it means

Thrown by CommonAbstractPanacheQueryImpl.checkRange when a range accessor method is called on a query whose Range state is null, i.e. range(int,int) was never invoked. Panache treats paging and ranging as mutually exclusive modes on a query; range accessors require ranged mode to be initialized first. It is an UnsupportedOperationException indicating incorrect API sequencing.

Source

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

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

View on GitHub (pinned to e1c734241f)

Solutions

  1. Call range(int startIndex, int lastIndex) on the PanacheQuery before accessing range-related methods.
  2. If the query is meant to be paged, switch the code to page(Page)/page(int,int) and page-related accessors.
  3. Guard the accessor call with your own knowledge of whether a range was set (track it in application code).

Example fix

// before
PanacheQuery<Person> q = Person.find("age > ?1", 18);
Range r = q.range(); // UnsupportedOperationException

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

Strategy: validation

Validate before calling

if (!rangedInitialized) { throw new IllegalStateException("call range(int, int) before reading the range"); }

Try / catch

try { Range r = query.range(); } catch (UnsupportedOperationException e) { query.range(0, defaultLast); Range r = query.range(); }

Prevention

When it happens

Trigger: Calling range() (the accessor) or any range-related method on a PanacheQuery before calling range(int startIndex, int lastIndex).

Common situations: Developers build a query and try to read back the configured range for logging/pagination logic without setting one; code paths conditionally call range() assuming it was configured upstream.

Related errors

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