{"record":{"id":"d1a7a913f995fe4f","repo":"jwtk/jjwt","slug":"unable-to-determine-a-suitable-mac-or-signature-al","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"UnsupportedKeyException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/DefaultJwtBuilder.java","lineNumber":199,"sourceCode":"    public JwtBuilder setHeaderParams(Map<String, ?> params) {\n        return header().add(params).and();\n    }\n\n    @Override\n    public JwtBuilder setHeaderParam(String name, Object value) {\n        return header().add(name, value).and();\n    }\n\n    protected static <K extends Key> SecureDigestAlgorithm<K, ?> forSigningKey(K key) {\n        Assert.notNull(key, \"Key cannot be null.\");\n        SecureDigestAlgorithm<K, ?> alg = StandardSecureDigestAlgorithms.findBySigningKey(key);\n        if (alg == null) {\n            String msg = \"Unable to determine a suitable MAC or Signature algorithm for the specified key using \" +\n                    \"available heuristics: either the key size is too weak be used with available algorithms, or the \" +\n                    \"key size is unavailable (e.g. if using a PKCS11 or HSM (Hardware Security Module) key store). \" +\n                    \"If you are using a PKCS11 or HSM keystore, consider using the \" +\n                    \"JwtBuilder.signWith(Key, SecureDigestAlgorithm) method instead.\";\n            throw new UnsupportedKeyException(msg);\n        }\n        return alg;\n    }\n\n    @Override\n    public JwtBuilder signWith(Key key) throws InvalidKeyException {\n        Assert.notNull(key, \"Key argument cannot be null.\");\n        SecureDigestAlgorithm<Key, ?> alg = forSigningKey(key); // https://github.com/jwtk/jjwt/issues/381\n        return signWith(key, alg);\n    }\n\n    @Override\n    public <K extends Key> JwtBuilder signWith(K key, final SecureDigestAlgorithm<? super K, ?> alg)\n            throws InvalidKeyException {\n\n        Assert.notNull(key, \"Key argument cannot be null.\");\n        if (key instanceof PublicKey) { // it's always wrong/insecure to try to create signatures with PublicKeys:\n            throw new IllegalArgumentException(PUB_KEY_SIGN_MSG);","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/DefaultJwtBuilder.java#L181-L217","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Specify the algorithm explicitly: jwt.signWith(key, Jwts.SIG.HS256) (or the appropriate SecureDigestAlgorithm) instead of relying on heuristics.","If signing with HMAC, supply a SecretKey of at least the required bit length (256+ bits for HS256).","Ensure the Key instance retains its encoded form (getEncoded() non-null) so size heuristics work, or construct it via Keys.hmacShaKeyFor(bytes).","Catch UnsupportedKeyException and retry with an explicit algorithm."],"exampleFix":"// before\nJwtBuilder b = Jwts.builder().signWith(hsmKey); // UnsupportedKeyException\n// after\nJwtBuilder b = Jwts.builder().signWith(hsmKey, Jwts.SIG.RS256);","handlingStrategy":"validation","validationCode":"if (key.getEncoded() == null || key.getEncoded().length * 8 < 256) { /* choose algorithm explicitly or use a stronger key */ }","typeGuard":null,"tryCatchPattern":"try { return builder.signWith(key).compact(); } catch (UnsupportedKeyException e) { return builder.signWith(key, Jwts.SIG.HS256).compact(); }","preventionTips":["Always pass an explicit SecureDigestAlgorithm to signWith","Use Keys.hmacShaKeyFor() with >=256-bit secrets","Be aware HSM/PKCS11 keys have no encoded size — always specify the algorithm for them"],"tags":["jwt","signing","key","hsm"],"backgroundTag":"invalid-argument-value","analyzedSha":"fb71496164c71442d08adec4571d9616ed5e1b8d","analyzedAt":"2026-09-09T00:33:09.982Z","contentChangedAt":"2026-09-09T00:33:09.982Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}