Analysis and Solution for IllegalArgumentException: Illegal Base64 Character in Java

Problem Background and Error Phenomenon

In Java web application development, user registration functionality typically requires sending confirmation emails to complete the verification process. A developer encountered java.lang.IllegalArgumentException: Illegal base64 character 5b exception during decoding while implementing this feature using JavaMail library and Java 8 Base64 utility class.

Error Code Analysis

The developer's original encoding code was:

byte[] encodedEmail = Base64.getUrlEncoder().encode(user.getEmail().getBytes(StandardCharsets.UTF_8));
String confirmLink = "Complete your registration by clicking on following"+ "\n<a href='" + confirmationURL + encodedEmail + "'>link</a>";

The problem occurred in the line encodedEmail + . Here, encodedEmail is a byte[] array. When directly concatenated with a string, Java invokes the array's toString() method, which returns the array's object identifier (such as [B@6499375d) rather than the actual Base64 encoded string.

Root Cause Analysis

The Base64.getUrlEncoder().encode() method returns a byte[] type containing the Base64 encoded byte sequence. When this byte array is directly converted to a string:

• Calling byte[].toString() does not convert byte content to a readable string
• It returns the JVM's internal object representation: [B@hash_value
• This format completely violates Base64 encoding specifications, causing illegal character errors during decoding

Correct Solution

The proper approach is to convert the Base64 encoded byte array to a string:

byte[] encodedBytes = Base64.getUrlEncoder().encode(user.getEmail().getBytes(StandardCharsets.UTF_8));
String encodedEmailString = new String(encodedBytes, StandardCharsets.UTF_8);
String confirmLink = "Complete your registration by clicking on following"
    + "\n<a href='" + confirmationURL + encodedEmailString + "'>link</a>";

Base64 Encoder Selection Analysis

Java 8 provides three types of Base64 encoders:

• Basic Encoder: Base64.getEncoder() - Uses standard Base64 character set
• URL Encoder: Base64.getUrlEncoder() - Uses URL-safe Base64 character set (replaces + and / with - and _)
• MIME Encoder: Base64.getMimeEncoder() - Suitable for MIME format

When used in URL parameters, Base64.getUrlEncoder() is the safer choice as it avoids special characters that require URL escaping.

Correct Implementation of Decoding Process

The decoding portion of the code was originally correct:

String encryptedEmail = request.getParameter("ID");
String decodedEmail = new String(Base64.getUrlDecoder().decode(encryptedEmail), StandardCharsets.UTF_8);

This uses the corresponding URL decoder, ensuring compatibility with the encoder and proper handling of URL-safe Base64 encoding.

Related Technical Points

From other answers, we can learn some related technical knowledge:

• When processing Base64 strings containing metadata (like data:image/png;base64,...), separate the pure Base64 portion first
• In scenarios like JWT, manual handling of Base64URL encoding padding character replacement may be necessary
• Always ensure encoding and decoding use matching encoder types

Best Practices Summary

To avoid similar Base64 encoding errors, it is recommended to:

1. Clearly distinguish between byte array and string conversions
2. Use URL-safe Base64 encoding for URL parameters
3. Use the same encoder type for both encoding and decoding
4. Validate encoding results to ensure they conform to Base64 format
5. Add exception handling and logging at critical positions

By following these best practices, developers can effectively avoid common errors like IllegalArgumentException: Illegal base64 character, improving code robustness and maintainability.