jwtk/jjwt · error · IllegalArgumentException

MAC ${keyType} key cannot be null.

Error message

MAC ${keyType} key cannot be null.

What it means

IllegalArgumentException from DefaultMacAlgorithm.validateKey when a null Key is passed for a MAC signing or verification operation. The keyType interpolates to 'signing' or 'verification' depending on direction.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java:155

        // We can ignore key name assertions for generic secrets, because HSM module key algorithm names
        // don't always align with JCA standard algorithm names
        boolean generic = KeysBridge.isGenericSecret(key);

        //assert key's jca name is valid if it's a JWA standard algorithm:
        if (!generic && isJwaStandard() && !isJwaStandardJcaName(name)) {
            throw new InvalidKeyException("The " + keyType(signing) + " key's algorithm '" + name +
                    "' does not equal a valid HmacSHA* algorithm name or PKCS12 OID and cannot be used with " +
                    getId() + ".");
        }
    }

    @Override
    protected void validateKey(Key k, boolean signing) {

        final String keyType = keyType(signing);
        if (k == null) {
            throw new IllegalArgumentException("MAC " + keyType + " key cannot be null.");
        }

        if (!(k instanceof SecretKey)) {
            String msg = "MAC " + keyType + " keys must be SecretKey instances.  Specified key is of type " +
                    k.getClass().getName();
            throw new InvalidKeyException(msg);
        }

        if (k instanceof Password) {
            String msg = "Passwords are intended for use with key derivation algorithms only.";
            throw new InvalidKeyException(msg);
        }

        final SecretKey key = (SecretKey) k;

        final String id = getId();

        assertAlgorithmName(key, signing);

View on GitHub (pinned to fb71496164)

Solutions

1. Ensure the key is created before signing/verifying: Jwts.SIG.HS256.key().build() or Keys.hmacShaKeyFor(bytes).
2. Fail fast at startup if the configured secret is missing rather than passing null.
3. Add a null-check/assertion at the call site before invoking signWith/verifyWith.
4. Fix the key-loading code path (env var, keystore) that returned null.

Example fix

// before
SecretKey key = System.getenv("JWT_SECRET") == null ? null : Keys.hmacShaKeyFor(env.getBytes());
Jwts.builder().signWith(key, Jwts.SIG.HS256);
// after
Objects.requireNonNull(key, "JWT signing key must be configured");
Jwts.builder().signWith(key, Jwts.SIG.HS256);

static SecretKey requireKey(SecretKey k) {
    return java.util.Objects.requireNonNull(k, "MAC signing/verification key must not be null");
}

boolean hasKey(Key k) { return k != null; }

try {
    return Jwts.builder().signWith(key, Jwts.SIG.HS256).compact();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("cannot be null")) throw new ConfigurationException("JWT key not configured");
    throw e;
}

When it happens

Trigger: Jwts.builder().signWith(null, HS256); Jwts.parser().verifyWith(null); passing a nullable key variable resolved from config/environment that ended up null.

Common situations: Missing signing-secret configuration resolved to null; a lookup that failed silently returning null key; refactoring that lost a default key assignment.

Related errors

• SecretKey byte array cannot be null.
• The ${keyType(signing)} key's algorithm cannot be null or em
• The ${keyType(signing)} key's algorithm '${name}' does not e
• MAC ${keyType} keys must be SecretKey instances. Specified
• The specified key byte array is bits which is not secure en

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