{"record":{"id":"890e24634d24543f","repo":"jwtk/jjwt","slug":"familyname-keytype-keys-must-be-secretkey-in","errorCode":null,"errorMessage":"${familyName} ${keyType} keys must be SecretKey instances.","messagePattern":"(.+?) (.+?) keys must be SecretKey instances\\.","errorType":"exception","errorClass":"InvalidKeyException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java","lineNumber":356,"sourceCode":"    private static String keyType(boolean signing) {\n        return signing ? \"signing\" : \"verification\";\n    }\n\n    /**\n     * @since 0.10.0\n     */\n    private void assertValid(Key key, boolean signing) throws InvalidKeyException {\n\n        if (this == NONE) {\n\n            String msg = \"The 'NONE' signature algorithm does not support cryptographic keys.\";\n            throw new InvalidKeyException(msg);\n\n        } else if (isHmac()) {\n\n            if (!(key instanceof SecretKey)) {\n                String msg = this.familyName + \" \" + keyType(signing) + \" keys must be SecretKey instances.\";\n                throw new InvalidKeyException(msg);\n            }\n            SecretKey secretKey = (SecretKey) key;\n\n            byte[] encoded = EMPTY_BYTES;\n            try {\n                encoded = secretKey.getEncoded();\n                if (encoded == null) {\n                    throw new InvalidKeyException(\"The \" + keyType(signing) + \" key's encoded bytes cannot be null.\");\n                }\n\n                String alg = secretKey.getAlgorithm();\n                if (alg == null) {\n                    throw new InvalidKeyException(\"The \" + keyType(signing) + \" key's algorithm cannot be null.\");\n                }\n\n                // These next checks use equalsIgnoreCase per https://github.com/jwtk/jjwt/issues/381#issuecomment-412912272\n                if (!HS256.jcaName.equalsIgnoreCase(alg) &&\n                        !HS384.jcaName.equalsIgnoreCase(alg) &&","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java#L338-L374","documentation":"Type guard inside SignatureAlgorithm.assertValid: when the algorithm is an HMAC family member (HS256/HS384/HS512), the JCA Signature for HMAC-SHA only accepts symmetric keys, so any key that is not a javax.crypto.SecretKey (e.g. an RSA PrivateKey or EC PublicKey passed to an HS* algorithm) is rejected with InvalidKeyException.","triggerScenarios":"Thrown at api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java:356 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Use a SecretKey with HMAC algorithms; create one via Keys.secretKeyFor(SignatureAlgorithm.HS256) (or HS384/HS512).","If the key is asymmetric (RSA/EC), switch the algorithm to the matching family (RS*/PS* for RSAKey, ES* for ECKey).","For string/byte-array secrets, wrap them with new SecretKeySpec(bytes, \"HmacSHA256\") matching the algorithm's JCA name."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"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"}