jwtk/jjwt · error · UnsupportedKeyException

Unable to determine a suitable MAC or Signature algorithm fo

Error message

Unable to determine a suitable MAC or Signature algorithm for the specified key using available heuristics: either the key size is too weak be used with available algorithms, or the key size is unavailable (e.g. if using a PKCS11 or HSM (Hardware Security Module) key store). If you are using a PKCS11 or HSM keystore, consider using the JwtBuilder.signWith(Key, SecureDigestAlgorithm) method instead.

What it means

When you call signWith(Key) without specifying an algorithm, JJWT inspects the key's encoded size and format to heuristically pick a MAC or signature algorithm. If the key is too small for any supported algorithm or its size cannot be determined (typical of PKCS11/HSM keys whose encoded form is unavailable), UnsupportedKeyException is thrown.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/DefaultJwtBuilder.java:199

    public JwtBuilder setHeaderParams(Map<String, ?> params) {
        return header().add(params).and();
    }

    @Override
    public JwtBuilder setHeaderParam(String name, Object value) {
        return header().add(name, value).and();
    }

    protected static <K extends Key> SecureDigestAlgorithm<K, ?> forSigningKey(K key) {
        Assert.notNull(key, "Key cannot be null.");
        SecureDigestAlgorithm<K, ?> alg = StandardSecureDigestAlgorithms.findBySigningKey(key);
        if (alg == null) {
            String msg = "Unable to determine a suitable MAC or Signature algorithm for the specified key using " +
                    "available heuristics: either the key size is too weak be used with available algorithms, or the " +
                    "key size is unavailable (e.g. if using a PKCS11 or HSM (Hardware Security Module) key store). " +
                    "If you are using a PKCS11 or HSM keystore, consider using the " +
                    "JwtBuilder.signWith(Key, SecureDigestAlgorithm) method instead.";
            throw new UnsupportedKeyException(msg);
        }
        return alg;
    }

    @Override
    public JwtBuilder signWith(Key key) throws InvalidKeyException {
        Assert.notNull(key, "Key argument cannot be null.");
        SecureDigestAlgorithm<Key, ?> alg = forSigningKey(key); // https://github.com/jwtk/jjwt/issues/381
        return signWith(key, alg);
    }

    @Override
    public <K extends Key> JwtBuilder signWith(K key, final SecureDigestAlgorithm<? super K, ?> alg)
            throws InvalidKeyException {

        Assert.notNull(key, "Key argument cannot be null.");
        if (key instanceof PublicKey) { // it's always wrong/insecure to try to create signatures with PublicKeys:
            throw new IllegalArgumentException(PUB_KEY_SIGN_MSG);

View on GitHub (pinned to fb71496164)

Solutions

1. Specify the algorithm explicitly: jwt.signWith(key, Jwts.SIG.HS256) (or the appropriate SecureDigestAlgorithm) instead of relying on heuristics.
2. If signing with HMAC, supply a SecretKey of at least the required bit length (256+ bits for HS256).
3. Ensure the Key instance retains its encoded form (getEncoded() non-null) so size heuristics work, or construct it via Keys.hmacShaKeyFor(bytes).
4. Catch UnsupportedKeyException and retry with an explicit algorithm.

Example fix

// before
JwtBuilder b = Jwts.builder().signWith(hsmKey); // UnsupportedKeyException
// after
JwtBuilder b = Jwts.builder().signWith(hsmKey, Jwts.SIG.RS256);

if (key.getEncoded() == null || key.getEncoded().length * 8 < 256) { /* choose algorithm explicitly or use a stronger key */ }

try { return builder.signWith(key).compact(); } catch (UnsupportedKeyException e) { return builder.signWith(key, Jwts.SIG.HS256).compact(); }

When it happens

Trigger: JwtBuilder.signWith(weakOrOpaqueKey) where the key is too short (e.g. an HMAC secret under the minimum length) or is a provider key (PKCS11/HSM) with no accessible encoded size, and no explicit algorithm was supplied.

Common situations: Using hardware-backed keys from an HSM or keystore; too-short HMAC secrets (e.g. a short password used as a signing key); opaque Key instances from custom providers.

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

• PublicKeys may not be used to create digital signatures. Pri
• The 'none' JWS algorithm cannot be used to sign JWTs.
• Cannot obtain required encoded bytes from key [${KeysBridge.
• Unexpected unsecured Claims JWT.
• Unexpected content JWS.

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