quarkusio/quarkus · error · IllegalArgumentException

Start index must be >= 0:

Error message

Start index must be >= 0: 

What it means

Range models an inclusive index window for queries (e.g. Range.of(start, end)). The constructor requires the start index to be non-negative; a negative start would produce an invalid query range, so it throws IllegalArgumentException.

Source

Thrown at extensions/panache/panache-common/runtime/src/main/java/io/quarkus/panache/common/Range.java:31

 * Range range = Range.of(0, 5);
 * </pre></code>
 *
 * Note that due to the end index being inclusive, it's impossible to write empty ranges.
 */
public class Range {
    // FIXME: bump to long? Jakarta Data uses longs for its Limit type
    private final int startIndex;
    private final int lastIndex;

    /**
     * Creates a new range
     *
     * @param startIndex the start index to include, 0-based
     * @param lastIndex the end index to include, 0-based
     */
    public Range(int startIndex, int lastIndex) {
        if (startIndex < 0)
            throw new IllegalArgumentException("Start index must be >= 0: " + startIndex);
        if (lastIndex < 0)
            throw new IllegalArgumentException("Last index must be >= 0: " + lastIndex);
        if (lastIndex < startIndex)
            throw new IllegalArgumentException(
                    "Last index must be >= start index: " + lastIndex + " is not larger or equal to " + startIndex);
        this.startIndex = startIndex;
        this.lastIndex = lastIndex;
    }

    /**
     * Creates a new range
     *
     * @param startIndex the start index to include, 0-based
     * @param lastIndex the end index to include, 0-based
     */
    public static Range of(int startIndex, int lastIndex) {
        return new Range(startIndex, lastIndex);
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Validate and clamp: Math.max(0, startIndex) before constructing the Range.
2. Return a 400 response for negative range input.
3. Prefer Page APIs (page(pageIndex, size)) and let Page validation surface clearer errors.

Example fix

// before
Range r = Range.of((page - 1) * size, page * size - 1); // page=0 -> -size
// after
int start = Math.max(0, (page - 1) * size);
Range r = Range.of(start, Math.max(start, page * size - 1));

int start = /* computed */;
if (start < 0) throw new BadRequestException("startIndex must be >= 0");
Range r = Range.of(start, last);

Range safeRange(int start, int last) {
    int s = Math.max(0, start);
    return Range.of(s, Math.max(s, last));
}

try {
    Range r = Range.of(start, last);
} catch (IllegalArgumentException e) {
    throw new BadRequestException("Invalid range: " + e.getMessage());
}

When it happens

Trigger: Calling new Range(-1, 10) or Range.of with a negative start, typically from unvalidated offsets, page math like (page-1)*size with page=0, or client input.

Common situations: Computing start from offset arithmetic that underflows; passing a negative "from" parameter from REST input; converting a 1-based page number to 0-based index incorrectly.

Related errors

• Last index must be >= 0:
• Last index must be >= start index: is not larger or equal t
• Limiting to 0 values is not supported
• Limiting to 0 values is not supported
• Limiting to 0 values is not supported

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