Theme

Error explainers · Base64 / Base64URL

Base64 decode error: invalid character

Standard Base64 uses only A–Z, a–z, 0–9, +, / and = for padding. The decoder met a character outside that alphabet. Usually the data is fine but has been transformed on the way: URL-encoded (%3D is an encoded =), written in the URL-safe alphabet, or wrapped in a prefix or a JWT. PasteKit names the bad character and its position, and accepts both the standard and URL-safe alphabets.

Seen as:

  • InvalidCharacterError: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.
  • InvalidCharacterError: String contains an invalid character
  • java.lang.IllegalArgumentException: Illegal base64 character 2d
  • binascii.Error: Only base64 data is allowed
  • System.FormatException: The input is not a valid Base-64 string as it contains a non-base 64 character, more than two padding characters, or an illegal character among the padding characters.

Input

Settings

History

Load from URL

Common causes

1. URL-encoded Base64

Base64 passed through a query string or cookie often arrives with =, + and / percent-encoded as %3D, %2B and %2F. Decode the URL encoding first (decodeURIComponent).

Before
eyJ1c2VyIjoiYWRhIiwicm9sZSI6ImFkbWluIn0%3D
After
eyJ1c2VyIjoiYWRhIiwicm9sZSI6ImFkbWluIn0=

2. URL-safe Base64 given to a standard decoder

Base64URL (used by JWTs and many APIs) replaces + and / with - and _ and often drops padding. Java reports - as “Illegal base64 character 2d”. Use the URL-safe decoder (Base64.getUrlDecoder(), base64.urlsafe_b64decode) or translate the two characters.

Before
PDw_Pz4-
After
PDw/Pz4+

3. A data URL or other prefix left in place

A data URL such as data:image/png;base64, is not part of the Base64 payload; neither is a label like Basic in an Authorization header. Strip everything up to and including the comma or space.

Before
Basic YWRhOnMzY3JldA==
After
YWRhOnMzY3JldA==

4. A whole JWT decoded as one Base64 string

A JWT is three Base64URL segments joined by dots, and the dot is not a Base64 character. Decode each segment separately, or use a JWT decoder.

Before
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc
After
eyJzdWIiOiIxIn0

Frequently asked questions

Are spaces and line breaks invalid in Base64?

MIME Base64 (email, PEM files) wraps lines at 76 characters, and most decoders, including atob and PasteKit, ignore whitespace. Strict decoders such as Python’s b64decode(validate=True) and Java’s basic decoder reject it.

What does "Illegal base64 character 2d" mean?

Java prints the offending character as a hex code: 2d is “-” and 5f is “_”, the URL-safe characters. 20 is a space and 25 is “%”, which points to URL encoding.

Why does Python sometimes say "Incorrect padding" instead?

Without validate=True, b64decode discards characters outside the alphabet and then finds that the remaining length is not a multiple of four. Missing = padding, common in Base64URL, causes the same message.

Related