{"record":{"id":"96cb82dc7f3fc507","repo":"jwtk/jjwt","slug":"the-keytype-signing-key-s-algorithm-cannot-be","errorCode":null,"errorMessage":"The ${keyType(signing)} key's algorithm cannot be null or empty.","messagePattern":"The (.+?) key's algorithm cannot be null or empty\\.","errorType":"validation","errorClass":"InvalidKeyException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java","lineNumber":135,"sourceCode":"        if (size >= mac.getKeyBitLength()) {\n            return mac;\n        }\n\n        return null; // couldn't find a suitable match\n    }\n\n\n    @Override\n    public SecretKeyBuilder key() {\n        return new DefaultSecretKeyBuilder(getJcaName(), getKeyBitLength());\n    }\n\n    private void assertAlgorithmName(SecretKey key, boolean signing) {\n\n        String name = key.getAlgorithm();\n        if (!Strings.hasText(name)) {\n            String msg = \"The \" + keyType(signing) + \" key's algorithm cannot be null or empty.\";\n            throw new InvalidKeyException(msg);\n        }\n\n        // We can ignore key name assertions for generic secrets, because HSM module key algorithm names\n        // don't always align with JCA standard algorithm names\n        boolean generic = KeysBridge.isGenericSecret(key);\n\n        //assert key's jca name is valid if it's a JWA standard algorithm:\n        if (!generic && isJwaStandard() && !isJwaStandardJcaName(name)) {\n            throw new InvalidKeyException(\"The \" + keyType(signing) + \" key's algorithm '\" + name +\n                    \"' does not equal a valid HmacSHA* algorithm name or PKCS12 OID and cannot be used with \" +\n                    getId() + \".\");\n        }\n    }\n\n    @Override\n    protected void validateKey(Key k, boolean signing) {\n\n        final String keyType = keyType(signing);","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java#L117-L153","documentation":"InvalidKeyException from DefaultMacAlgorithm.assertAlgorithmName (called from validateKey) when a SecretKey's JCA algorithm name is null or empty. MAC algorithms like HS256 need to verify the key's algorithm matches the Hmac family, which requires a non-empty name.","triggerScenarios":"Constructing a SecretKeySpec with a null/empty algorithm string and passing it to Jwts.builder().signWith(key, HS256) or parser verifyWith; deserializing a key from a store that dropped the algorithm attribute.","commonSituations":"new SecretKeySpec(bytes, \"\") or new SecretKeySpec(bytes, null); custom SecretKey implementations returning null from getAlgorithm(); keys built by third-party crypto providers with incomplete metadata.","solutions":["Specify a valid algorithm name: new SecretKeySpec(bytes, \"HmacSHA256\") for HS256.","Let jjwt create the key: Jwts.SIG.HS256.key().build() or Keys.secretKeyFor(SignatureAlgorithm).","If wrapping a raw secret, use io.jsonwebtoken.security.Keys.hmacShaKeyFor(bytes) which sets the proper algorithm.","Fix the custom SecretKey implementation to return a non-empty algorithm name."],"exampleFix":"// before\nSecretKey key = new SecretKeySpec(secretBytes, \"\");\nJwts.parser().verifyWith(key).build().parseSignedClaims(jwt);\n// after\nSecretKey key = Keys.hmacShaKeyFor(secretBytes); // algorithm set automatically\nJwts.parser().verifyWith(key).build().parseSignedClaims(jwt);","handlingStrategy":"type-guard","validationCode":"static SecretKey requireNamedSecretKey(SecretKey k) {\n    if (k == null || k.getAlgorithm() == null || k.getAlgorithm().isEmpty())\n        throw new IllegalArgumentException(\"MAC key must have a non-empty algorithm name\");\n    return k;\n}","typeGuard":"boolean hasAlgorithmName(Key k) {\n    return k instanceof SecretKey && k.getAlgorithm() != null && !k.getAlgorithm().isEmpty();\n}","tryCatchPattern":"try {\n    return Jwts.builder().signWith(key, Jwts.SIG.HS256).compact();\n} catch (InvalidKeyException e) {\n    logger.error(\"Invalid MAC key: {}\", e.getMessage());\n    throw e;\n}","preventionTips":["Always use Keys.hmacShaKeyFor(bytes) which sets the algorithm name correctly","Never call new SecretKeySpec(bytes, null) or with \"\"","Check third-party SecretKey implementations return a proper algorithm name"],"tags":["java","jjwt","mac","invalid-key","hmac"],"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"}