{"record":{"id":"238d1f0c7ebfb621","repo":"jwtk/jjwt","slug":"secretkey-byte-array-cannot-be-null","errorCode":null,"errorMessage":"SecretKey byte array cannot be null.","messagePattern":"SecretKey byte array cannot be null\\.","errorType":"exception","errorClass":"InvalidKeyException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/io/jsonwebtoken/security/Keys.java","lineNumber":62,"sourceCode":"    }\n\n    //prevent instantiation\n    private Keys() {\n    }\n\n    /**\n     * Creates a new SecretKey instance for use with HMAC-SHA algorithms based on the specified key byte array.\n     *\n     * @param bytes the key byte array\n     * @return a new SecretKey instance for use with HMAC-SHA algorithms based on the specified key byte array.\n     * @throws WeakKeyException if the key byte array length is less than 256 bits (32 bytes) as mandated by the\n     *                          <a href=\"https://tools.ietf.org/html/rfc7518#section-3.2\">JWT JWA Specification\n     *                          (RFC 7518, Section 3.2)</a>\n     */\n    public static SecretKey hmacShaKeyFor(byte[] bytes) throws WeakKeyException {\n\n        if (bytes == null) {\n            throw new InvalidKeyException(\"SecretKey byte array cannot be null.\");\n        }\n\n        int bitLength = bytes.length * 8;\n\n        //Purposefully ordered higher to lower to ensure the strongest key possible can be generated.\n        if (bitLength >= 512) {\n            return new SecretKeySpec(bytes, \"HmacSHA512\");\n        } else if (bitLength >= 384) {\n            return new SecretKeySpec(bytes, \"HmacSHA384\");\n        } else if (bitLength >= 256) {\n            return new SecretKeySpec(bytes, \"HmacSHA256\");\n        }\n\n        String msg = \"The specified key byte array is \" + bitLength + \" bits which \" +\n                \"is not secure enough for any JWT HMAC-SHA algorithm.  The JWT \" +\n                \"JWA Specification (RFC 7518, Section 3.2) states that keys used with HMAC-SHA algorithms MUST have a \" +\n                \"size >= 256 bits (the key size must be greater than or equal to the hash \" +\n                \"output size).  Consider using the Jwts.SIG.HS256.key() builder (or HS384.key() \" +","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/api/src/main/java/io/jsonwebtoken/security/Keys.java#L44-L80","documentation":"Keys.hmacShaKeyFor throws InvalidKeyException when the byte array passed for building an HMAC-SHA SecretKey is null. A null key material cannot produce a usable signing key, so the library fails immediately before any length checks.","triggerScenarios":"Calling Keys.hmacShaKeyFor(null), typically when a secret was never loaded — e.g. an environment variable or config property is missing so the byte array variable is null.","commonSituations":"Missing JWT_SECRET env var in deployment, config loader returning null silently, or decoding a Base64 secret that was empty/absent.","solutions":["Ensure the secret bytes are non-null before calling: load and validate the env/config value","Fail fast at startup with a clear message if the secret is absent","Decode the secret (e.g. Base64) and assert it is non-empty prior to key construction"],"exampleFix":"// before\nSecretKey key = Keys.hmacShaKeyFor(secretBytes); // NPE-ish InvalidKeyException if null\n// after\nif (secretBytes == null || secretBytes.length == 0) throw new IllegalStateException(\"JWT secret not configured\");\nSecretKey key = Keys.hmacShaKeyFor(secretBytes);","handlingStrategy":"validation","validationCode":"if (secretBytes == null || secretBytes.length == 0) {\n    throw new IllegalStateException(\"JWT secret not configured (env JWT_SECRET missing or empty)\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    key = Keys.hmacShaKeyFor(secretBytes);\n} catch (InvalidKeyException e) {\n    throw new IllegalStateException(\"Invalid JWT secret configuration\", e);\n}","preventionTips":["Validate required secret config at application startup, before first use","Fail fast on null/empty secrets with a configuration-specific message","Never let config loaders silently substitute null for missing secrets"],"tags":["java","jjwt","hmac","null-argument"],"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"}