What causes "wrap(e, jcaName, specifiedProvider, null)" in jwtk/jjwt?

Inspect the wrapped cause (e.getCause()) — it names the real JCA failure (InvalidKeyException, InvalidAlgorithmParameterException, ...).

jwtk/jjwt · error

wrap(e, jcaName, specifiedProvider, null)

Error message

wrap(e, jcaName, specifiedProvider, null)

What it means

JcaTemplate.get wraps any unexpected Exception from the JCA call into a runtime security exception via wrap(e, jcaName, ...). Unlike the NoSuchAlgorithmException branch (268), this covers all other JCA failures: InvalidKeyException, InvalidAlgorithmParameterException, provider runtime errors, etc., annotated with the JCA name and provider attempted.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/security/JcaTemplate.java:404

                    // and we haven't tried BC yet, so try that now:
                    Provider fallback = findBouncyCastle();
                    if (fallback != null) { // BC found, try again:
                        try {
                            T value = doGet(jcaName, fallback);
                            // record the successful attempt so we don't have to do this again:
                            FALLBACK_ATTEMPTS.putIfAbsent(jcaName, Boolean.TRUE);
                            return value;
                        } catch (Throwable ignored) {
                            // record the failed attempt so we don't keep trying and propagate original exception:
                            FALLBACK_ATTEMPTS.putIfAbsent(jcaName, Boolean.FALSE);
                        }
                    }
                }
                // otherwise, we tried the fallback, or there isn't a fallback, so no need to try again, so
                // propagate the exception:
                throw wrap(nsa, jcaName, specifiedProvider, null);
            } catch (Exception e) {
                throw wrap(e, jcaName, specifiedProvider, null);
            }
        }

        protected abstract T doGet(String jcaName, Provider provider) throws Exception;

        // visible for testing:
        protected Exception wrap(Exception e, String jcaName, Provider specifiedProvider, Provider fallbackProvider) {
            String msg = "Unable to obtain '" + jcaName + "' " + getId() + " instance from ";
            if (specifiedProvider != null) {
                msg += "specified '" + specifiedProvider + "' Provider";
            } else {
                msg += "default JCA Provider";
            }
            if (fallbackProvider != null) {
                msg += " or fallback '" + fallbackProvider + "' Provider";
            }
            msg += ": " + e.getMessage();
            return wrap(msg, e);

View on GitHub (pinned to fb71496164)

Solutions

Inspect the wrapped cause (e.getCause()) — it names the real JCA failure (InvalidKeyException, InvalidAlgorithmParameterException, ...).
Validate key sizes/parameters before use (e.g. 256-bit AES keys, matching curve and algorithm).
Ensure the specified provider actually supports the jcaName transformation.
Catch the thrown runtime exception around Jwts.parser()/builder() calls and log the full cause chain.

Example fix

// before
SecretKey key = new SecretKeySpec(new byte[8], "AES"); // too short -> InvalidKeyException wrapped
// after
byte[] bytes = new byte[32];
new SecureRandom().nextBytes(bytes);
SecretKey key = new SecretKeySpec(bytes, "AES");
try {
    Jwts.builder().encryptWith(key, ...).compact();
} catch (JwtException e) {
    logger.error("JCA failure: " + e.getCause(), e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// validate key size before use
if (key.getEncoded() != null && key.getEncoded().length < 32)
    throw new InvalidKeyException("AES key must be at least 256 bits");

Try / catch

try {
    return Jwts.parser().decryptWith(key).build().parseEncryptedClaims(token);
} catch (JwtException e) {
    log.error("JCA operation failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);
    throw new AuthenticationException(e);
}

Prevention

Always use keys of the exact required length (128/192/256-bit AES)
Always log the cause chain — the root JCA exception names the real problem
Use SecureRandom-generated keys from jjwt's builders
Verify provider configuration before deployment (FIPS/HSO environments)

When it happens

Trigger: Any exception thrown by the underlying JCA engine during doGet — e.g. a SecretKey derived with wrong parameters, a Cipher given an invalid key length, key strength exceeding crypto export policy, or a provider throwing a runtime error — during JWT sign/verify/encrypt/decrypt.

Common situations: AES keys of invalid length (e.g. 100-bit key), GCM params mismatch, signing with an EC key whose curve params were altered, provider misconfiguration, or hardware tokens returning errors.

Related errors

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