Understanding the "illegal base64 character" error (Java, Groovy and Mule 4 - DW 2.0)

Updated: Sep 4

Github repository with the Mule Project can be found at the end of the post.

Are you familiar with the fromBase64 or the toBase64 functions from DataWeave 2.0? What about the getUrlEncoder or the getEncoder functions from Java? Do you know the differences between the “basic” Base 64 encoding and the “URL and Filename safe” Base 64 encoding? Well, you may have guessed it by now, but you’re about to find out the answers to these questions!

Or maybe you’re here because you keep getting the “Illegal base64 character” error in DataWeave. Even if you get this error using any other programming language, this post can help you understand why it is happening.

The Problem

I was recently presented with this problem when Maria Isabel Vargas asked a question about base64 decoding in a Slack channel. She was using the fromBase64 function that’s available in Mule 4 - DataWeave 2.0 inside the dw::core::Binaries module to transform a basic Base 64 string into a binary value.

The problem was that the server was returning a Base 64 URL Encoded String (e.g. “cHJvc3RkZXY_YmxvZw==”) opposed to the basic Base 64 string from which the fromBase64 function attempts to transform. As a result, the Transform Message component was returning this error: “Illegal base64 character 5f". This error happens when the string that you are trying to transform contains a character not recognized by the basic Base 64 Alphabet (in this case it was an underscore character). Below you can see which characters are accepted.

Since the server was using the Base 64 URL encoding, the string that we were trying to decode in DataWeave contained different characters from the ones above because the Base 64 URL has a different alphabet. You can see this alphabet below.

Notice that the characters 62 and 63 differ from the basic Base 64 Alphabet and the Base 64 URL Alphabet. The first one contains the characters plus (+) and slash (/), while the second one uses the characters minus (-) and underline (_).

In other words, if you have an encoded string like "cHJvc3RkZXY_YmxvZw==", you wouldn’t be able to transform it using a basic Base64 decoder because it contains characters that are not recognized by its alphabet (the underline character).

You can get these two errors when you try to transform a Base 64 URL string using the fromBase64 DW function (at least when this post was created):

  • java.lang.IllegalArgumentException: Illegal base64 character 5f (when containing an underscore)

  • java.lang.IllegalArgumentException: Illegal base64 character 2d (when containing a minus)