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.

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)

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}
• Unexpected unsecured Claims JWT.
• Unexpected content JWS.
• Unexpected Claims JWS.
• Unexpected content JWE.

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