jwtk/jjwt · error · java.lang.IllegalArgumentException

Strict decoding: Last encoded character (before the…

Error message

Strict decoding: Last encoded character (before the paddings if any) is a valid base 64 alphabet but not a possible encoding. Decoding requires at least two trailing 6-bit characters to create bytes.

What it means

Error "Strict decoding: Last encoded character (before the paddings if any) is a valid base 64 alphabet but not a possible encoding. Decoding requires at least two trailing 6-bit characters to create bytes." thrown in jwtk/jjwt.

Solutions

1. Ensure the Base64 input is complete: the final quantum must contain at least two Base64 characters (the encoded data may be truncated — check transport/serialization for dropped characters)
2. Re-encode the source bytes with a canonical Base64 encoder
3. Pad or fix the encoded string at the source; do not append arbitrary characters to 'fix' the length, as that changes the decoded bytes

When it happens

Trigger: Thrown at impl/src/main/java/io/jsonwebtoken/impl/io/Base64Codec.java:789 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/6f85bf41813c11a5. Report an issue: GitHub.

Appendix: source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/io/Base64Codec.java:789

     */
    private void validateCharacter(final int emptyBitsMask, final Context context) {
        if (isStrictDecoding() && (context.ibitWorkArea & emptyBitsMask) != 0) {
            throw new IllegalArgumentException(
                    "Strict decoding: Last encoded character (before the paddings if any) is a valid " +
                            "base 64 alphabet but not a possible encoding. " +
                            "Expected the discarded bits from the character to be zero.");
        }
    }

    /**
     * Validates whether decoding allows an entire final trailing character that cannot be
     * used for a complete byte.
     *
     * @throws IllegalArgumentException if strict decoding is enabled
     */
    private void validateTrailingCharacter() {
        if (isStrictDecoding()) {
            throw new IllegalArgumentException(
                    "Strict decoding: Last encoded character (before the paddings if any) is a valid " +
                            "base 64 alphabet but not a possible encoding. " +
                            "Decoding requires at least two trailing 6-bit characters to create bytes.");
        }
    }

}

View on GitHub (pinned to fb71496164)