jwtk/jjwt · error · InvalidKeyException

The ${keyType} key's encoded bytes cannot be null.

Error message

The ${keyType} key's encoded bytes cannot be null.

What it means

Validation check in SignatureAlgorithm.assertValid for HMAC algorithms: after confirming the key is a SecretKey, the helper calls getEncoded() and rejects keys whose encoded form is null. Some provider-backed or hardware-backed SecretKeys (e.g. PKCS11 tokens) return null from getEncoded(), which prevents jjwt from inspecting key size, so the key is deemed unusable.

Source

Thrown at api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java:364

        if (this == NONE) {

            String msg = "The 'NONE' signature algorithm does not support cryptographic keys.";
            throw new InvalidKeyException(msg);

        } else if (isHmac()) {

            if (!(key instanceof SecretKey)) {
                String msg = this.familyName + " " + keyType(signing) + " keys must be SecretKey instances.";
                throw new InvalidKeyException(msg);
            }
            SecretKey secretKey = (SecretKey) key;

            byte[] encoded = EMPTY_BYTES;
            try {
                encoded = secretKey.getEncoded();
                if (encoded == null) {
                    throw new InvalidKeyException("The " + keyType(signing) + " key's encoded bytes cannot be null.");
                }

                String alg = secretKey.getAlgorithm();
                if (alg == null) {
                    throw new InvalidKeyException("The " + keyType(signing) + " key's algorithm cannot be null.");
                }

                // These next checks use equalsIgnoreCase per https://github.com/jwtk/jjwt/issues/381#issuecomment-412912272
                if (!HS256.jcaName.equalsIgnoreCase(alg) &&
                        !HS384.jcaName.equalsIgnoreCase(alg) &&
                        !HS512.jcaName.equalsIgnoreCase(alg) &&
                        !HS256.pkcs12Name.equals(alg) &&
                        !HS384.pkcs12Name.equals(alg) &&
                        !HS512.pkcs12Name.equals(alg)) {
                    throw new InvalidKeyException("The " + keyType(signing) + " key's algorithm '" + alg +
                            "' does not equal a valid HmacSHA* algorithm name and cannot be used with " + name() + ".");
                }

View on GitHub (pinned to fb71496164)

Solutions

1. Use a software SecretKey whose getEncoded() returns bytes, e.g. Keys.secretKeyFor(SignatureAlgorithm.HS256) or new SecretKeySpec(bytes, jcaName).
2. If the key comes from a keystore/HSM that cannot expose encoded bytes, extract the raw secret material at provisioning time and re-create an exportable SecretKeySpec.
3. Choose an algorithm family that does not need encoded bytes, or restructure key storage to keep the secret retrievable.

When it happens

Trigger: Thrown at api/src/main/java/io/jsonwebtoken/SignatureAlgorithm.java:364 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/26ba4f1ba69bf1fe. Report an issue: GitHub.