quarkusio/quarkus · error · IllegalArgumentException

`offset` must be greater or equal to 0

Error message

`offset` must be greater or equal to 0

What it means

Thrown by BitFieldArgs.get when constructing a BITFIELD GET subcommand with an Offset whose underlying offset value is negative. Redis bitfield offsets address bits from the start of the string (or from the end when negative in Redis semantics, which this API models via the Offset(boolean, int) wrapper instead); passing a raw negative int to the typed Offset overload would address an invalid position, so the argument guard rejects it before the command is serialized.

Source

Thrown at extensions/redis-client/runtime/src/main/java/io/quarkus/redis/datasource/bitmap/BitFieldArgs.java:148

     * @return the current {@code BitFieldArgs}
     */
    public BitFieldArgs get(BitFieldType bft, int offset) {
        return get(bft, new Offset(false, offset));
    }

    /**
     * Adds a new {@code GET} subcommand.
     *
     * @param bft the bit field type, must not be {@code null}.
     * @param offset bitfield offset
     * @return the current {@code BitFieldArgs}
     */
    public BitFieldArgs get(BitFieldType bft, Offset offset) {
        if (offset == null) {
            throw new IllegalArgumentException("`offset` must not be `null`");
        }
        if (offset.offset < 0) {
            throw new IllegalArgumentException("`offset` must be greater or equal to 0");
        }

        this.previousBitFieldType = bft;
        this.commands.addAll(List.of("GET", bft.toString(), offset.toString()));
        return this;
    }

    /**
     * Adds a new {@code SET} subcommand.
     *
     * @param bft the bit field type, must not be {@code null}.
     * @param offset bitfield offset
     * @param value the value
     * @return the current {@code BitFieldArgs}
     */
    public BitFieldArgs set(BitFieldType bft, int offset, long value) {
        return set(bft, new Offset(false, offset), value);
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a bit offset >= 0 (offsets are in bits, from 0)
2. Clamp or validate the computed offset before constructing Offset
3. Use the Offset.byType(...) factories, which derive valid offsets from the field width

Example fix

// before
int pos = index * 8 - 8; // can be -8 for index 0
args.get(bft, new BitFieldArgs.Offset(pos));
// after
int pos = Math.max(0, index * 8 - 8);
args.get(bft, new BitFieldArgs.Offset(pos));

if (offsetValue < 0) { throw new IllegalArgumentException("bit offset must be >= 0"); }
args.get(bft, new BitFieldArgs.Offset(offsetValue));

static boolean isValidOffset(long v) { return v >= 0; }

try { args.get(bft, new BitFieldArgs.Offset(pos)); } catch (IllegalArgumentException e) { pos = 0; args.get(bft, new BitFieldArgs.Offset(pos)); }

When it happens

Trigger: new BitFieldArgs.Offset(-1) or any negative offset passed to get(), often from a computed offset like byteIndex * 8 + shift where shift became negative.

Common situations: Arithmetic errors computing bit positions; confusing bit offset with byte index; underflow when subtracting offsets.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid integer encoding for a bit field type: " + bit + ".
• `bits` must be strictly positive
• Signed integers support only up to 64 bits
• Unsigned integers support only up to 63 bits
• The offset must be greater or equals to 0

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