jwtk/jjwt · error · java.lang.IllegalArgumentException

bitLength must be an even multiple of 8

Error message

bitLength must be an even multiple of 8

What it means

DefaultSecretKeyBuilder requires bitLength to be a whole number of bytes (an even multiple of 8, via Byte.SIZE) so it can construct a SecretKey of exact byte length. A bit length not divisible by 8 cannot be represented cleanly as a byte array, so the constructor throws IllegalArgumentException immediately.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/security/DefaultSecretKeyBuilder.java:36

import io.jsonwebtoken.lang.Assert;
import io.jsonwebtoken.security.SecretKeyBuilder;

import javax.crypto.SecretKey;

/**
 * @since 0.12.0
 */
public class DefaultSecretKeyBuilder extends AbstractSecurityBuilder<SecretKey, SecretKeyBuilder>
        implements SecretKeyBuilder {

    protected final String JCA_NAME;
    protected final int BIT_LENGTH;

    public DefaultSecretKeyBuilder(String jcaName, int bitLength) {
        this.JCA_NAME = Assert.hasText(jcaName, "jcaName cannot be null or empty.");
        if (bitLength % Byte.SIZE != 0) {
            String msg = "bitLength must be an even multiple of 8";
            throw new IllegalArgumentException(msg);
        }
        this.BIT_LENGTH = Assert.gt(bitLength, 0, "bitLength must be > 0");
        random(Randoms.secureRandom());
    }

    @Override
    public SecretKey build() {
        JcaTemplate template = new JcaTemplate(JCA_NAME, this.provider, this.random);
        return template.generateSecretKey(this.BIT_LENGTH);
    }
}

View on GitHub (pinned to fb71496164)

Solutions

1. Pass a bit length divisible by 8 (e.g. 128, 192, 256).
2. Compute the size from bytes and multiply: bytes * 8.
3. Validate the value before constructing the builder.

Example fix

// before
new DefaultSecretKeyBuilder("AES", 127);
// after
new DefaultSecretKeyBuilder("AES", 128);

if (bitLength <= 0 || bitLength % 8 != 0) {
    throw new IllegalArgumentException("bitLength must be a positive multiple of 8");
}

try {
    builder = new MySecretKeyBuilder("AES", bitLength);
} catch (IllegalArgumentException e) {
    // correct bitLength to the nearest byte multiple
}

When it happens

Trigger: Instantiating a secret key builder subclass or calling a builder API with bitLength values like 100, 127, or 521; typically from custom MAC/direct key algorithm code that passes an odd bit size.

Common situations: Typos in bit sizes (e.g. 127 instead of 128), using curve-style bit sizes (521) for symmetric keys, or programmatic computation producing a non-multiple-of-8 value.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unexpected unsecured Claims JWT.
• Unexpected content JWS.
• Unexpected Claims JWS.
• Unexpected content JWE.
• Unexpected Claims JWE.

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