{"record":{"id":"ce235bc9cfe3f8f8","repo":"jwtk/jjwt","slug":"illegal-name-character-c","errorCode":null,"errorMessage":"Illegal ${name} character: '${c}'","messagePattern":"Illegal (.+?) character: '(.+?)'","errorType":"exception","errorClass":"DecodingException","httpStatus":null,"severity":"error","filePath":"api/src/main/java/io/jsonwebtoken/io/Base64.java","lineNumber":221,"sourceCode":"            }\n            // Add the bytes\n            dArr[d++] = (byte) (i >> 16);\n            if (d < len) {\n                dArr[d++] = (byte) (i >> 8);\n                if (d < len) {\n                    dArr[d++] = (byte) i;\n                }\n            }\n        }\n        return dArr;\n    }\n    */\n\n    private int ctoi(char c) {\n        int i = c > IALPHABET_MAX_INDEX ? -1 : IALPHABET[c];\n        if (i < 0) {\n            String msg = \"Illegal \" + getName() + \" character: '\" + c + \"'\";\n            throw new DecodingException(msg);\n        }\n        return i;\n    }\n\n    /**\n     * Decodes a BASE64-encoded {@code CharSequence} that is known to be reasonably well formatted. The preconditions\n     * are:<br>\n     * + The sequence must have a line length of 76 chars OR no line separators at all (one line).<br>\n     * + Line separator must be \"\\r\\n\", as specified in RFC 2045\n     * + The sequence must not contain illegal characters within the encoded string<br>\n     * + The sequence CAN have illegal characters at the beginning and end, those will be dealt with appropriately.<br>\n     *\n     * @param seq The source sequence. Length 0 will return an empty array. <code>null</code> will throw an exception.\n     * @return The decoded array of bytes. May be of length 0.\n     * @throws DecodingException on illegal input\n     */\n    byte[] decodeFast(CharSequence seq) throws DecodingException {\n","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/api/src/main/java/io/jsonwebtoken/io/Base64.java#L203-L239","documentation":"Base64.ctoi maps each character to its 6-bit value using the Base64 alphabet; if a character is outside the alphabet (index lookup returns -1) JJWT throws DecodingException with 'Illegal <Base64/Base64Url> character'. This guards the decode path in Base64.decode/Base64Url against malformed input. getName() reports whether the Base64 or Base64Url variant rejected the character.","triggerScenarios":"Calling Jwts.parser() on a token whose signature or payload segment contains characters not valid for the variant being decoded — e.g. '+' or '/' in a Base64Url segment, whitespace/newlines inside a token pasted from an email or PDF, quotes or trailing period, or decoding arbitrary text with JJWT's Base64/Base64Url utility directly.","commonSituations":"JWT copied with line breaks or smart quotes; token signed/encoded with standard Base64 but decoded as Base64Url (or vice versa); storing tokens in systems that wrap lines; hand-rolling JWT parsing and passing the whole token (with dots) where only a segment should be decoded.","solutions":["Inspect the offending character shown in the message and remove/fix it in the input (whitespace, quotes, wrapping are the usual culprits)","Use the correct decoder for your data: Jwts.parser() for full JWTs, Base64Url for URL-safe segments, Base64 only for standard-base64 data","Normalize input before decoding: strip whitespace/newlines and re-encode if the source used the wrong alphabet","Parse the JWT with its dedicated API instead of manually base64-decoding segments so segment boundaries are handled for you"],"exampleFix":"// before\nbyte[] sig = Base64Url.decode(token.replace(\"\\n\", \"\").getBytes()); // still may contain '+'\n// DecodingException: Illegal Base64Url character: '+'\n\n// after\nJws<Claims> jws = Jwts.parserBuilder().build().parseClaimsJws(token.trim());","handlingStrategy":"validation","validationCode":"// Java: strip whitespace and validate base64url alphabet before decoding\nboolean isBase64Url(String s) {\n    return s != null && s.matches(\"[A-Za-z0-9_-]*\");\n}\nString sanitize(String s) {\n    return s == null ? null : s.replaceAll(\"\\\\s+\", \"\").replace(\"\\\"\", \"\");\n}","typeGuard":"boolean isDecodableSegment(String segment) {\n    return segment != null && !segment.isEmpty()\n        && segment.matches(\"[A-Za-z0-9_-]+=\"); // base64url chars only\n}","tryCatchPattern":"try {\n    byte[] decoded = Base64Url.decode(segment);\n} catch (DecodingException e) {\n    // segment contained an illegal character; reject or re-encode input\n}","preventionTips":["Strip whitespace, newlines, and quotes from any base64/base64url data before decoding","Use Base64Url for JWT and URL contexts, Base64 only for standard-base64 data","Parse full JWTs with Jwts.parser() rather than manually decoding segments","Never wrap JWTs at storage/display time (disable line wrapping in emails, logs, config files)","Check the character named in the message to diagnose alphabet mismatches quickly"],"tags":["base64","decoding","malformed-input"],"backgroundTag":"invalid-argument-format","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"}