jwtk/jjwt · error · IllegalArgumentException

${msg}

Error message

${msg}

What it means

Thrown by io.jsonwebtoken.lang.Assert.notEmpty(byte[], String) (since 0.12.0) when the supplied byte array is null or empty. JJWT uses it to reject empty key material or other byte-based inputs, since cryptographic operations require at least one byte. It throws java.lang.IllegalArgumentException with the caller's message and returns the array when valid.

Solutions

1. Verify the byte array's source (file, env var, decoder) actually produced bytes; log array.length before the call.
2. Fix the key loading path: correct the file path/env var and confirm the decode produced data.
3. Fail fast with your own check so the error message points at the real configuration problem.

Example fix

// before
byte[] keyBytes = Base64.getDecoder().decode(System.getenv("JWT_SECRET")); // blank -> may throw or yield empty
Keys.hmacShaKeyFor(keyBytes);
// after
String secret = System.getenv("JWT_SECRET");
Assert.notNull(secret, "JWT_SECRET not set");
byte[] keyBytes = Base64.getDecoder().decode(secret);
if (keyBytes.length == 0) throw new IllegalArgumentException("JWT_SECRET decodes to empty bytes");
Keys.hmacShaKeyFor(keyBytes);

if (keyBytes == null || keyBytes.length == 0) {
    throw new IllegalArgumentException("key bytes are missing or empty");
}

boolean hasBytes(byte[] b) { return b != null && b.length > 0; }

try {
    SecretKey key = Keys.hmacShaKeyFor(keyBytes);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Invalid key material: " + e.getMessage(), e);
}

When it happens

Trigger: Calling Assert.notEmpty(byte[] array, msg) with array == null or array.length == 0; passing empty key bytes to key builders (SecretKeySpec-style construction), signing keys, or claim values routed through this assertion.

Common situations: Reading a signing key from an env var or file that resolved to empty bytes (missing file, blank env variable); decoding a base64 key string that failed silently and produced a zero-length array; supplying an empty PEM/DER payload to a key parser.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• ${message}
• bitLength must be an even multiple of 8
• constant [ ] does not exist in enum type
• derivedKeyBitLength may not exceed
• EC JWK x,y coordinates do not exist on elliptic curve

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

Appendix: source

Thrown at api/src/main/java/io/jsonwebtoken/lang/Assert.java:237

     * @param array the array to check
     * @throws IllegalArgumentException if the object array is <code>null</code> or has no elements
     */
    public static void notEmpty(Object[] array) {
        notEmpty(array, "[Assertion failed] - this array must not be empty: it must contain at least 1 element");
    }

    /**
     * Assert that the specified byte array is not null and has at least one byte element.
     *
     * @param array the byte array to check
     * @param msg   the exception message to use if the assertion fails
     * @return the byte array if the assertion passes
     * @throws IllegalArgumentException if the byte array is null or empty
     * @since 0.12.0
     */
    public static byte[] notEmpty(byte[] array, String msg) {
        if (Objects.isEmpty(array)) {
            throw new IllegalArgumentException(msg);
        }
        return array;
    }

    /**
     * Assert that the specified character array is not null and has at least one byte element.
     *
     * @param chars the character array to check
     * @param msg   the exception message to use if the assertion fails
     * @return the character array if the assertion passes
     * @throws IllegalArgumentException if the character array is null or empty
     * @since 0.12.0
     */
    public static char[] notEmpty(char[] chars, String msg) {
        if (Objects.isEmpty(chars)) {
            throw new IllegalArgumentException(msg);
        }
        return chars;

View on GitHub (pinned to fb71496164)