{"record":{"id":"62aca667ae982d29","repo":"jwtk/jjwt","slug":"bitlength-argument-must-be-0","errorCode":null,"errorMessage":"bitLength argument must be >= 0","messagePattern":"bitLength argument must be >= 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/lang/Bytes.java","lineNumber":224,"sourceCode":"     * Returns the minimum number of bytes required to represent the specified number of bits.\n     *\n     * <p>This is defined/used by many specifications, such as:</p>\n     * <ul>\n     *     <li><a href=\"https://www.rfc-editor.org/rfc/rfc7518.html#section-2\">JWA RFC 7518, Section 2</a>'s\n     *     <code>Base64urlUInt</code> definition</li>\n     *     <li>Elliptic Curve <code>Integer-to-OctetString</code> conversion defined by Section 2.3.7 of the\n     *     <a href=\"http://www.secg.org/sec1-v2.pdf\">Standards for Efficient Cryptography Group,\n     *     &qupt;SEC 1: Elliptic Curve Cryptography&quot; Version 2.0, May 2009</a> (as required by\n     *     <a href=\"https://www.rfc-editor.org/rfc/rfc7518.html#section-3.4\">RFC 7518, Section 3.4</a>)</li>\n     *     <li>and others.</li>\n     * </ul>\n     *\n     * @param bitLength the number of bits to represent as a byte array, must be >= 0\n     * @return the minimum number of bytes required to represent the specified number of bits.\n     * @throws IllegalArgumentException if {@code bitLength} is less than zero.\n     */\n    public static int length(int bitLength) {\n        if (bitLength < 0) throw new IllegalArgumentException(\"bitLength argument must be >= 0\");\n        return (bitLength + 7) / Byte.SIZE;\n    }\n\n    public static String bitsMsg(long bitLength) {\n        return bitLength + \" bits (\" + bitLength / Byte.SIZE + \" bytes)\";\n    }\n\n    public static String bytesMsg(int byteArrayLength) {\n        return bitsMsg((long) byteArrayLength * Byte.SIZE);\n    }\n\n    public static void increment(byte[] a) {\n        for (int i = a.length - 1; i >= 0; --i) {\n            if (++a[i] != 0) {\n                break;\n            }\n        }\n    }","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/lang/Bytes.java#L206-L242","documentation":"Bytes.length(bitLength) computes the minimum number of bytes needed to represent a given number of bits and validates that the input is not negative, throwing IllegalArgumentException otherwise. It is a pure size utility used when sizing keys/byte arrays.","triggerScenarios":"Calling Bytes.length(negativeBitLength), typically when the bit length came from a misconfigured key size, a failed parse (Integer.parseInt of bad input producing unexpected math), or an arithmetic result that underflowed.","commonSituations":"Key-size configuration read as negative (e.g. '-1' default when unset); subtracting header overhead from a size and going below zero; computing bit length of an empty/missing value.","solutions":["Clamp or validate before the call: if (bitLength < 0) throw/defaults.","Fix the source of the negative number - usually an unset config value or a bad subtraction.","Use a positive constant (e.g. 256 for a 256-bit key) instead of derived values where possible."],"exampleFix":"// before\nint bytes = Bytes.length(keyBits - overheadBits); // can go negative\n// after\nint bits = Math.max(keyBits - overheadBits, 0);\nif (bits <= 0) throw new IllegalStateException(\"key size underflow\");\nint bytes = Bytes.length(bits);","handlingStrategy":"validation","validationCode":"if (bitLength < 0) {\n    throw new IllegalArgumentException(\"bitLength must be >= 0, got \" + bitLength);\n}\nint bytes = Bytes.length(bitLength);","typeGuard":null,"tryCatchPattern":"try {\n    int len = Bytes.length(bits);\n} catch (IllegalArgumentException e) {\n    // log and use configured default key size\n}","preventionTips":["Sanity-check derived sizes: use Math.max(0, computed)","Fail fast on unset config values instead of using -1 sentinels","Prefer explicit constants for key sizes"],"tags":["bytes","bit-length","argument-validation"],"backgroundTag":"value-out-of-range","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"}