{"record":{"id":"8f626da96c7fae4e","repo":"jwtk/jjwt","slug":"the-id-algorithm-requires-type-with-a-leng","errorCode":null,"errorMessage":"The '${id}' algorithm requires ${type} with a length of ${bitsMsg(requiredLengthInBits)}.  The provided key has a length of ${bitsMsg(bitLen)}.","messagePattern":"The '(.+?)' algorithm requires (.+?) with a length of (.+?)\\.  The provided key has a length of (.+?)\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/security/AesAlgorithm.java","lineNumber":138,"sourceCode":"            if (propagate) {\n                throw re;\n            }\n            //can't get the bytes to validate, e.g. hardware security module or later Android, so just return:\n            return null;\n        }\n        long keyBitLength = Bytes.bitLength(keyBytes);\n        if (keyBitLength < requiredBitLength) {\n            throw new WeakKeyException(lengthMsg(getId(), \"keys\", requiredBitLength, keyBitLength));\n        }\n\n        return keyBytes;\n    }\n\n    protected byte[] assertBytes(byte[] bytes, String type, int requiredBitLen) {\n        long bitLen = Bytes.bitLength(bytes);\n        if (requiredBitLen != bitLen) {\n            String msg = lengthMsg(getId(), type, requiredBitLen, bitLen);\n            throw new IllegalArgumentException(msg);\n        }\n        return bytes;\n    }\n\n    byte[] assertIvLength(final byte[] iv) {\n        return assertBytes(iv, \"initialization vectors\", this.ivBitLength);\n    }\n\n    byte[] assertTag(byte[] tag) {\n        return assertBytes(tag, \"authentication tags\", this.tagBitLength);\n    }\n\n    byte[] assertDecryptionIv(IvSupplier src) throws IllegalArgumentException {\n        byte[] iv = src.getIv();\n        Assert.notEmpty(iv, DECRYPT_NO_IV);\n        return assertIvLength(iv);\n    }\n","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/security/AesAlgorithm.java#L120-L156","documentation":"IllegalArgumentException from AesAlgorithm.assertBytes when an input byte array (typically an IV/nonce or GCM tag) does not exactly equal the required bit length, as opposed to keys which only need a minimum. The exact match requirement comes from the JWA spec (e.g. 96-bit GCM IVs).","triggerScenarios":"Supplying a custom IV of non-96-bit length to a GCM algorithm via a custom AesAlgorithm instance or Asserting a tag buffer whose size differs from the algorithm's tagBitLength; usually only hit when extending/using low-level algorithm APIs.","commonSituations":"Hand-rolling an AES-GCM IV that is 16 bytes (128 bits) instead of 12 bytes (96 bits); truncating or padding a tag during custom decryption; reusing code written for CBC (16-byte IV) with GCM.","solutions":["Use a 12-byte (96-bit) IV for AES-GCM: SecureRandom-generated byte[12].","Let the library generate the IV itself instead of supplying one.","Ensure tag buffers are the full algorithm tag size (e.g. 128 bits for GCM default).","If using CBC-style algorithms, confirm required IV bit length matches the block size (128 bits)."],"exampleFix":"// before\nbyte[] iv = new byte[16]; // 128-bit IV\nbyte[] tag = ...;\nalg.encrypt(new SecureRequest<>(plaintext, key).setIv(iv));\n// after\nbyte[] iv = new byte[12]; // 96-bit GCM IV\nnew SecureRandom().nextBytes(iv);\nalg.encrypt(new SecureRequest<>(plaintext, key).setIv(iv));","handlingStrategy":"validation","validationCode":"static byte[] newGcmIv() {\n    byte[] iv = new byte[12]; // 96 bits\n    new SecureRandom().nextBytes(iv);\n    return iv;\n}\nassert iv.length * 8 == 96 : \"GCM IV must be 96 bits\";","typeGuard":null,"tryCatchPattern":"try {\n    alg.encrypt(req.iv(iv));\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"initialization vectors\")) {\n        req.iv(newGcmIv()); // regenerate correct-size IV\n    } else throw e;\n}","preventionTips":["Use 12-byte IVs for AES-GCM, 16-byte for AES-CBC - know your algorithm","Prefer letting jjwt generate IVs instead of supplying your own","Never reuse a GCM IV with the same key","Keep a constant IV_LENGTH per algorithm in your crypto utility class"],"tags":["java","jjwt","aes-gcm","iv-length","jwe"],"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"}