TheAlgorithms/Java · error · IllegalArgumentException

Padding '=' can only appear at the end (last 1 or 2 characte

Error message

Padding '=' can only appear at the end (last 1 or 2 characters)

What it means

Base64.decode enforces that the '=' padding character may only appear in the last one or two positions of the input. Padding earlier in the string (firstPadding < length - 2) indicates corruption, mis-encoding, or a string that was concatenated incorrectly. RFC 4648 permits at most two trailing '=' characters.

Source

Thrown at src/main/java/com/thealgorithms/conversions/Base64.java:124

    public static byte[] decode(String input) {
        if (input == null) {
            throw new IllegalArgumentException("Input cannot be null");
        }

        if (input.isEmpty()) {
            return new byte[0];
        }

        // Strict RFC 4648 compliance: length must be a multiple of 4
        if (input.length() % 4 != 0) {
            throw new IllegalArgumentException("Invalid Base64 input length; must be multiple of 4");
        }

        // Validate padding: '=' can only appear at the end (last 1 or 2 chars)
        int firstPadding = input.indexOf('=');
        if (firstPadding != -1) {
            if (firstPadding < input.length() - 2) {
                throw new IllegalArgumentException("Padding '=' can only appear at the end (last 1 or 2 characters)");
            }
            for (int i = firstPadding; i < input.length(); i++) {
                if (input.charAt(i) != '=') {
                    throw new IllegalArgumentException("A padding '=' must not be followed by a non-padding character");
                }
            }
        }

        List<Byte> result = new ArrayList<>();

        // Process input in groups of 4 characters
        for (int i = 0; i < input.length(); i += 4) {
            // Get up to 4 characters
            int char1 = getBase64Value(input.charAt(i));
            int char2 = getBase64Value(input.charAt(i + 1));
            int char3 = input.charAt(i + 2) == '=' ? 0 : getBase64Value(input.charAt(i + 2));
            int char4 = input.charAt(i + 3) == '=' ? 0 : getBase64Value(input.charAt(i + 3));

View on GitHub (pinned to fdfb9a395b)

Solutions

1. Re-encode the original bytes with a standard Base64 encoder rather than constructing strings by hand.
2. Validate padding position before calling decode and reject/repair the source data.
3. Use java.util.Base64.getDecoder() which enforces the same rules but gives clearer standard error messages.

Example fix

// before
String bad = "AB=CD===";
byte[] out = Base64.decode(bad); // '=' too early

// after
String good = Base64.encodeString(originalBytes); // let encoder place padding
byte[] out = Base64.decode(good);

String s = input.replaceAll("\\s", "");
int firstPad = s.indexOf('=');
if (firstPad != -1 && firstPad < s.length() - 2) {
    throw new IllegalArgumentException("padding misplaced");
}
byte[] out = Base64.decode(s);

static boolean hasValidPaddingPosition(String s) {
    s = s.replaceAll("\\s", "");
    int fp = s.indexOf('=');
    return fp == -1 || fp >= s.length() - 2;
}

try {
    byte[] out = Base64.decode(input);
} catch (IllegalArgumentException e) {
    throw new DomainException("Malformed Base64: " + e.getMessage(), e);
}

When it happens

Trigger: Input like "AB=C" where '=' appears in the middle. Input with three or more trailing '=' characters. Input where padding was inserted at the wrong position during manual construction.

Common situations: Manually building Base64 strings without proper padding logic. Corrupted data from a transport that inserted characters. Copy errors when transcribing tokens.

Related errors

• A padding '=' must not be followed by a non-padding characte
• Invalid Base64 input length; must be multiple of 4
• Input cannot be null
• Invalid Base64 character: {}
• Slope and intercept must be valid numbers.

AI-assisted analysis of TheAlgorithms/Java@fdfb9a395b (2026-08-13). Data as JSON: /api/errors/a033f2da0214268b. Report an issue: GitHub.