{"record":{"id":"71b8c9e0c28f0ac8","repo":"jwtk/jjwt","slug":"mac-keytype-key-cannot-be-null","errorCode":null,"errorMessage":"MAC ${keyType} key cannot be null.","messagePattern":"MAC (.+?) key cannot be null\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java","lineNumber":155,"sourceCode":"\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);\n        if (k == null) {\n            throw new IllegalArgumentException(\"MAC \" + keyType + \" key cannot be null.\");\n        }\n\n        if (!(k instanceof SecretKey)) {\n            String msg = \"MAC \" + keyType + \" keys must be SecretKey instances.  Specified key is of type \" +\n                    k.getClass().getName();\n            throw new InvalidKeyException(msg);\n        }\n\n        if (k instanceof Password) {\n            String msg = \"Passwords are intended for use with key derivation algorithms only.\";\n            throw new InvalidKeyException(msg);\n        }\n\n        final SecretKey key = (SecretKey) k;\n\n        final String id = getId();\n\n        assertAlgorithmName(key, signing);","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/security/DefaultMacAlgorithm.java#L137-L173","documentation":"IllegalArgumentException from DefaultMacAlgorithm.validateKey when a null Key is passed for a MAC signing or verification operation. The keyType interpolates to 'signing' or 'verification' depending on direction.","triggerScenarios":"Jwts.builder().signWith(null, HS256); Jwts.parser().verifyWith(null); passing a nullable key variable resolved from config/environment that ended up null.","commonSituations":"Missing signing-secret configuration resolved to null; a lookup that failed silently returning null key; refactoring that lost a default key assignment.","solutions":["Ensure the key is created before signing/verifying: Jwts.SIG.HS256.key().build() or Keys.hmacShaKeyFor(bytes).","Fail fast at startup if the configured secret is missing rather than passing null.","Add a null-check/assertion at the call site before invoking signWith/verifyWith.","Fix the key-loading code path (env var, keystore) that returned null."],"exampleFix":"// before\nSecretKey key = System.getenv(\"JWT_SECRET\") == null ? null : Keys.hmacShaKeyFor(env.getBytes());\nJwts.builder().signWith(key, Jwts.SIG.HS256);\n// after\nObjects.requireNonNull(key, \"JWT signing key must be configured\");\nJwts.builder().signWith(key, Jwts.SIG.HS256);","handlingStrategy":"validation","validationCode":"static SecretKey requireKey(SecretKey k) {\n    return java.util.Objects.requireNonNull(k, \"MAC signing/verification key must not be null\");\n}","typeGuard":"boolean hasKey(Key k) { return k != null; }","tryCatchPattern":"try {\n    return Jwts.builder().signWith(key, Jwts.SIG.HS256).compact();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"cannot be null\")) throw new ConfigurationException(\"JWT key not configured\");\n    throw e;\n}","preventionTips":["Fail fast at application startup if the configured secret is missing","Wrap environment/config lookups so a missing value throws at load time, not sign time","Use Optional<Key> and orElseThrow at wiring time"],"tags":["java","jjwt","null-argument","mac","hmac"],"backgroundTag":"null-argument","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"}