jwtk/jjwt · error · IllegalArgumentException

${message}

Error message

${message}

What it means

Assert.isTrue validates a boolean precondition and throws IllegalArgumentException with the caller-supplied message when the expression is false. The JJWT library uses it internally to enforce argument contracts before proceeding (e.g. key sizes, algorithm compatibility, positive numbers). It is a fail-fast guard, not a runtime state error.

Source

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

 * increasing cyclomatic complexity.
 */
public final class Assert {

    private Assert() {
    } //prevent instantiation

    /**
     * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
     * if the test result is <code>false</code>.
     * <pre class="code">Assert.isTrue(i &gt; 0, "The value must be greater than zero");</pre>
     *
     * @param expression a boolean expression
     * @param message    the exception message to use if the assertion fails
     * @throws IllegalArgumentException if expression is <code>false</code>
     */
    public static void isTrue(boolean expression, String message) {
        if (!expression) {
            throw new IllegalArgumentException(message);
        }
    }

    /**
     * Assert a boolean expression, throwing <code>IllegalArgumentException</code>
     * if the test result is <code>false</code>.
     * <pre class="code">Assert.isTrue(i &gt; 0);</pre>
     *
     * @param expression a boolean expression
     * @throws IllegalArgumentException if expression is <code>false</code>
     */
    public static void isTrue(boolean expression) {
        isTrue(expression, "[Assertion failed] - this expression must be true");
    }

    /**
     * Assert that an object is <code>null</code> .
     * <pre class="code">Assert.isNull(value, "The value must be null");</pre>

View on GitHub (pinned to fb71496164)

Solutions

1. Read the exception message; it names the exact predicate that failed and the offending value.
2. Fix the argument so the stated condition holds (e.g. supply a key of sufficient length, a positive number).
3. Validate the value with an explicit check or Assert-style guard in your own code before calling the JJWT API so the failure surfaces at the call site.
4. Check version migration notes if the precondition changed after a library upgrade.

Example fix

// before
Key key = Keys.hmacShaKeyFor(shortSecret.getBytes()); // 10 bytes -> IllegalArgumentException
// after
byte[] bytes = secret.getBytes(StandardCharsets.UTF_8);
if (bytes.length < 32) { throw new IllegalArgumentException("HS256 needs >= 256-bit key"); }
SecretKey key = Keys.hmacShaKeyFor(bytes);

if (!(keyBytes.length * 8 >= 256)) {
    throw new IllegalArgumentException("HS256 requires a key of at least 256 bits");
}

try {
    // JJWT call with checked argument
} catch (IllegalArgumentException e) {
    log.error("invalid argument for JWT API: " + e.getMessage());
    throw new ConfigurationException(e.getMessage(), e);
}

When it happens

Trigger: Any JJWT API call whose internal Assert.isTrue(expression, message) check evaluates false — e.g. passing a key whose bit length or algorithm does not satisfy a required predicate, or a numeric argument that must be > 0 but is 0/negative.

Common situations: Using an HMAC key shorter than the algorithm requires (e.g. 128-bit key for HS256 after upgrading), configuring a negative or zero clock-skew/lease value, or swapping arguments so a condition that was previously true becomes false.

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/d59bb488f5142a0f. Report an issue: GitHub.