jwtk/jjwt · error · IllegalArgumentException

Byte array must be at least ${bitsMsg(this.bitLength)}. Foun

Error message

Byte array must be at least ${bitsMsg(this.bitLength)}. Found ${bitsMsg(len)}

What it means

RequiredBitLengthConverter.assertLength also enforces a minimum: when the converter is non-exact, a byte array whose bit length is less than the configured bitLength triggers this IllegalArgumentException stating the minimum required bits and the actual found bits.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/lang/RequiredBitLengthConverter.java:44

    public RequiredBitLengthConverter(Converter<byte[], Object> converter, int bitLength) {
        this(converter, bitLength, true);
    }

    public RequiredBitLengthConverter(Converter<byte[], Object> converter, int bitLength, boolean exact) {
        this.converter = Assert.notNull(converter, "Converter cannot be null.");
        this.bitLength = Assert.gt(bitLength, 0, "bitLength must be greater than 0");
        this.exact = exact;
    }

    private byte[] assertLength(byte[] bytes) {
        long len = Bytes.bitLength(bytes);
        if (exact && len != this.bitLength) {
            String msg = "Byte array must be exactly " + Bytes.bitsMsg(this.bitLength) + ". Found " + Bytes.bitsMsg(len);
            throw new IllegalArgumentException(msg);
        } else if (len < this.bitLength) {
            String msg = "Byte array must be at least " + Bytes.bitsMsg(this.bitLength) + ". Found " + Bytes.bitsMsg(len);
            throw new IllegalArgumentException(msg);
        }
        return bytes;
    }

    @Override
    public Object applyTo(byte[] bytes) {
        assertLength(bytes);
        return this.converter.applyTo(bytes);
    }

    @Override
    public byte[] applyFrom(Object o) {
        byte[] result = this.converter.applyFrom(o);
        return assertLength(result);
    }
}

View on GitHub (pinned to fb71496164)

Solutions

1. Increase the array length so len >= requiredBits (e.g. use a full digest output instead of a truncated one).
2. Generate keys of adequate size for the algorithm (256-bit keys for HS256, etc.).
3. Validate byte array length before passing it in.

Example fix

// before
byte[] key = "secret".getBytes(); // 48 bits
// after
byte[] key = new byte[32]; // 256 bits, e.g. from a secure random generator

void requireMinBits(byte[] b, long bits) {
    long len = b.length * 8L;
    if (len < bits) throw new IllegalArgumentException("Need at least " + bits + " bits, got " + len);
}

try {
    converter.applyTo(bytes);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Byte array must be at least")) {
        // supply longer key material
    }
    throw e;
}

When it happens

Trigger: Supplying a too-short byte array where at least bitLength bits are required, e.g. a 64-bit value where the claim demands >= 128 bits.

Common situations: Using short/weak secrets as keys; truncated hashes; mistaken units (passing 16 bytes where 16 bits were thought sufficient, or vice versa).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Byte array must be exactly ${bitsMsg(this.bitLength)}. Found
• ${i.getClass()} getId() cannot be null or empty.
• Value must be a positive integer.
• Unsupported value type. Expected: ${type.getName()}, found:
• Invalid AES key length: ${bitsMsg(keyBitLength)}. AES only s

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/377c4a17af24cee1. Report an issue: GitHub.