top of page

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

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)

The Solution

Java contains a function called getUrlDecoder, which is used to decode a string that was encoded using the Base 64 URL alphabet. This is exactly the problem that we were trying to solve. But before you start panicking and coding your solution using Java and creating a whole Java class, it's way easier to just use the Mule 4 Scripting Module. I’ll show you how.

This module should already be installed in your Studio. However, if you can’t see it, you can download it from Exchange. Alternatively, you can use the “Add Modules” button from Anypoint Studio, which is located on your Mule Palette.

After that, you can simply take the Execute component and drag-and-drop it into your flow. For this demonstration, I will be using an HTTP Listener as a trigger, and I will send the encoded string in the body of the request from Postman.

Once you have the Execute component, you can select “Groovy” as your Engine and paste the following line of code into your script:


You should end up with this:

As you can see in this Groovy script, we are using the getUrlDecoder function to decode whatever is in our payload. The result will be returned to our Postman application in the body of the response.

You need to make sure that the payload that is sent to the Groovy script is a Java String. So, let’s add a Transform Message right after the HTTP Listener and transform the payload into a Java string. Like this:

Let’s start this Mule app and test!

We send the same string as before (cHJvc3RkZXY_YmxvZw==) from Postman, and we expect to get the decoded message as a response.

And… it worked!

Try it yourself

Do you want to experiment a bit more with all of this? For sure! Let me give you a quick guide on how to do this.

1. Encode the bytes/string into a Basic 64 URL encoded string

You will need Java (or you can also do it in Mule 4 using a Groovy script) to get the encoded string first. You don’t need to download and install Java onto your computer to do this; you can search for a free online Java compiler like this one: TutorialsPoint Java Compiler

There, just copy and paste this Java code:

Next, click on “Execute” in the top left corner. You will see the encoded string on the right side of the website (the last line in the white background). Copy this string and save it somewhere so that you can use it in the next steps.

2. Create your Mule App in Anypoint Studio

Follow the steps explained previously in “The Solution”, or paste this code into the XML configuration of your file:

3. Create a Postman request

If you don’t have Postman, you can download it for free from here: Postman Download. When you open it, you just have to click on the plus (+) button as you can see here:

Then, add this in the Request URL section:


And add the previously copied string inside the Request Body. Don’t forget to select “Raw” and “Text” from the two dropdowns that are over the request body text area.

4. Run your Mule App

Once it is deployed successfully, you can click on the big blue “Send” button from Postman and see the results which should match the string you encoded in Step 1 (using Java).


Let’s do a quick recap on what we just learned from this post:

  1. The basic Base 64 alphabet can recognize the characters plus (+) and slash (/).

  2. The Base 64 URL alphabet can recognize the characters minus (-) and underline (_).

  3. Depending on how a string was encoded (using basic Base 64 or Base 64 URL encoding), it can include any of the characters from the chosen alphabet.

  4. An encoded string with one alphabet may not be decoded using the other alphabet’s decoding system. If the decoder attempts to read an unrecognized character, it’ll send an Illegal base64 character error message.

  5. You can’t decode a Base 64 URL string with the fromBase64 DataWeave 2.0 function.

  6. You can decode a Base 64 URL string by using an Execute component along with a Groovy engine and the getUrlDecoder Java function.

Had you seen this error before? How did you solve it?

Sign-up to leave a comment below!




GitHub repository

131,398 views8 comments

8 comentarii

wella test
wella test
10 mai 2023

Hi Alex,

I am trying to encode pdf containing some text and images/logos to base 64. I need to send endoded base 64 content to external system. I tried to encode pdf with tobase() function in dataweave and using the java function which you have given in your blog. But base64 content generated using these two ways is not correct. When external system is generating pdf from base 64 content , the resulting pdf is showing error as 'Message: Illegal character: 41' . Basically images/logos in PDF are not loading properly When I send base 64 content generated using online tool ( then external system is able to generate PDF properly from it.

Alex Martinez
Alex Martinez
10 mai 2023
Răspunde utilizatorului

That is so interesting! I have never tried it with pdfs. If you think this is a bug, feel free to raise an issue here:

You can also ask a question to the wider community using Stack Overflow with the DataWeave tag:


Hi Alexandra

This is super helpful!! It worked like a charm :) I am glad that you helped me to resolve ths issue on priority and also you have given all the related links and explanations to help in the concept intake. Loving to find out this team on the interwebs ! Thank you so very much !

Warm Regards


Alex Martinez
Alex Martinez
11 mar. 2021
Răspunde utilizatorului

Happy to help! 😁


Hi Alexendra

I have recieved your response via email so writing again. I am receiving below payload from an external system :


My goal is to convert this to json. For this I did the same scripting tool->groovy script execution by feeding java input of this payload. I am receiving below error when posting from postman:

java.lang.IllegalArgumentException: Illegal base64 character 25

Please let me know how can I fix this.

Thank Yiu


Alex Martinez
Alex Martinez
11 mar. 2021
Răspunde utilizatorului

Hi @Tanushree!

Your string is not a Base64 encoded payload, it's a URI component string.

To convert that string into a JSON format, you can use this code:

%dw 2.0 output application/json import * from dw::core::URL --- read(decodeURIComponent(payload))

You can read more about the URL module here:

and the read function here:

Why is it not a base64 encoded string?

The error message mentions a character 25, which is a percentage (%) character (from Hex:

If you take a look at the Base64 alphabet in this blog post, for both regular and URL encoding, none of them include the percentage character. For this same reason, it wouldn't be able to decode a string that contains a percentage character (% - 25…


Kishan Mohan
Kishan Mohan
29 sept. 2020

Thanks for this post @Alex, for URL encoding do we need to use Java? Is there any option to generate byte array from a string payload? If yes, then it seems we can use Base64.getUrlencoder().encode(payload)

Alex Martinez
Alex Martinez
11 mar. 2021
Răspunde utilizatorului

Hi Kishan! No, you don't need to use Java. This was just an example that's using Java. And, yes! You can use that function to encode inside the Groovy script :) I didn't use it in this example because the problem was just to decode what was received from the server.

bottom of page