apache/dubbo · error · IllegalArgumentException

base642bytes: base64 string length % 4 == 1.

Error message

base642bytes: base64 string length % 4 == 1.

What it means

Thrown by the String-alphabet Base64 decoder when the supplied segment length `len` satisfies len % 4 == 1. Every valid Base64 group encodes 3 bytes into 4 characters, so a total length congruent to 1 mod 4 is impossible for any well-formed Base64 (with or without padding) and is rejected with IllegalArgumentException before any decoding.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/io/Bytes.java:636

            throw new IndexOutOfBoundsException("base642bytes: offset < 0, offset is " + off);
        }
        if (len < 0) {
            throw new IndexOutOfBoundsException("base642bytes: length < 0, length is " + len);
        }
        if (len == 0) {
            return new byte[0];
        }
        if (off + len > str.length()) {
            throw new IndexOutOfBoundsException("base642bytes: offset + length > string length.");
        }

        if (code.length() < 64) {
            throw new IllegalArgumentException("Base64 code length < 64.");
        }

        int rem = len % 4;
        if (rem == 1) {
            throw new IllegalArgumentException("base642bytes: base64 string length % 4 == 1.");
        }

        int num = len / 4, size = num * 3;
        if (code.length() > 64) {
            if (rem != 0) {
                throw new IllegalArgumentException("base642bytes: base64 string length error.");
            }

            char pc = code.charAt(64);
            if (str.charAt(off + len - 2) == pc) {
                size -= 2;
                --num;
                rem = 2;
            } else if (str.charAt(off + len - 1) == pc) {
                size--;
                --num;
                rem = 3;
            }

View on GitHub (pinned to 3a3043227f)

Solutions

1. Re-source the original Base64 string (it has been truncated/corrupted).
2. If you intentionally slice, slice on a 4-char boundary: len -= (len % 4) before decoding (only if dropping trailing chars is acceptable).
3. Validate/repair: pad with '=' to a multiple of 4 only when the input is known-padded and the alphabet has a pad char.

Example fix

// before
byte[] b = Bytes.base642bytes(truncatedStr, 0, truncatedStr.length(), C64); // len % 4 == 1
// after
// re-fetch the full, untruncated Base64 string, then:
byte[] b = Bytes.base642bytes(fullStr, 0, fullStr.length(), C64);

if (len % 4 == 1) throw new IllegalArgumentException("not valid base64: len % 4 == 1");
byte[] b = Bytes.base642bytes(str, off, len, Bytes.C64);

static boolean isBase64LengthOk(int len) {
    return len % 4 != 1;
}

try {
    byte[] b = Bytes.base642bytes(str, off, len, Bytes.C64);
} catch (IllegalArgumentException e) {
    // truncated input — re-fetch or reject
    throw new IllegalArgumentException("base64 input truncated/corrupt", e);
}

When it happens

Trigger: Decoding a string/segment whose character count is 1, 5, 9, ... i.e. len % 4 == 1; a truncated Base64 payload missing several trailing chars; a region length computed incorrectly so it lands on 1 mod 4.

Common situations: Truncation of a Base64 blob in transit or in a property file; copy-paste that dropped trailing characters; an off/len slice that cut a 4-group mid-block leaving 1 char.

Related errors

• base642bytes: base64 string length error.
• base642bytes: offset < 0, offset is {}
• base642bytes: length < 0, length is {}
• base642bytes: offset + length > string length.
• hex string format error [${c}].

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/693db292b74327c4. Report an issue: GitHub.