quarkusio/quarkus · error · IllegalArgumentException

Unsigned integers support only up to 63 bits

Error message

Unsigned integers support only up to 63 bits

What it means

An unsigned Redis bit-field integer is limited to 63 bits because the library holds values in a signed Java long; 64 unsigned bits could overflow into the sign bit. Widths >= 64 are rejected with IllegalArgumentException.

Source

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

                this.bits = Integer.parseInt(bit.substring(1));
            } else if (bit.startsWith("u")) {
                this.signed = false;
                this.bits = Integer.parseInt(bit.substring(1));
            }
            throw new IllegalArgumentException("Invalid integer encoding for a bit field type: " + bit +
                    ". It must start with `i` (signed integers) or `u` (unsigned integers)");
        }

        public BitFieldType(boolean signed, int bits) {
            if (bits <= 0) {
                throw new IllegalArgumentException("`bits` must be strictly positive");
            }

            if (signed && bits >= 65) {
                throw new IllegalArgumentException("Signed integers support only up to 64 bits");
            }
            if (!signed && bits >= 64) {
                throw new IllegalArgumentException("Unsigned integers support only up to 63 bits");
            }

            this.signed = signed;
            this.bits = bits;
        }

        @Override
        public String toString() {
            return (signed ? "i" : "u") + bits;
        }

    }

    /**
     * Represents a bit field offset.
     * See also <a href="https://redis.io/commands/bitfield#bits-and-positional-offsets">Bits and positional offsets</a>
     */
    public static class Offset {

View on GitHub (pinned to e1c734241f)

Solutions

1. Use at most 63 bits for unsigned types
2. Use BitFieldArgs.BitFieldType.unsignedIn63() for the widest unsigned type
3. Use a signed 64-bit field if the value fits in long range

Example fix

// before
new BitFieldArgs.BitFieldType(false, 64);
// after
new BitFieldArgs.BitFieldType(false, 63);

if (!signed && bits >= 64) { throw new IllegalArgumentException("unsigned width must be <= 63"); }

static boolean isValidUnsignedWidth(int bits) { return bits >= 1 && bits <= 63; }

try { type = new BitFieldArgs.BitFieldType(false, bits); } catch (IllegalArgumentException e) { type = BitFieldArgs.BitFieldType.unsignedIn63(); }

When it happens

Trigger: new BitFieldArgs.BitFieldType(false, 64) or higher; parsing "u64" or "u128"; using the same width constant for signed and unsigned variants.

Common situations: Assuming u64 is valid since i64 is; porting code that used 64-bit unsigned masks; modeling 128-bit unsigned values.

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
• `offset` must be greater or equal to 0
• The offset must be greater or equals to 0

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