"Invalid character" / Invalid Base64 String Error, Explained
Base64 decoders are strict about their alphabet and padding — a string that looks fine to the eye can still fail because of one wrong character or a missing =.
What triggers it
- Wrong alphabet. Standard base64 uses
+and/; URL-safe base64 (used in JWTs and query strings) uses-and_instead. Feeding a URL-safe string to a standard decoder (or vice versa) throws an invalid-character error on the first-or_it hits. - Missing or wrong padding. Standard base64 pads the output to a multiple of 4 characters with
=. A string with the wrong number of padding characters, or padding in the middle instead of the end, fails to decode. URL-safe base64 as used in JWTs typically omits padding entirely — decoders that expect it need to add it back before decoding. - Whitespace or line breaks. Some contexts (email attachments, certain config files) wrap base64 output at a fixed line width. A strict decoder that doesn't strip whitespace first will reject the embedded newlines.
- It's simply not base64. Plain text that happens to contain only letters and numbers can look like base64 but have an invalid length or fail entirely once a non-alphabet character shows up.
How to fix it
Identify which alphabet you actually have — if it contains - or _, treat it as URL-safe base64. Strip surrounding whitespace, and pad the length to a multiple of 4 with = if your decoder requires it. The Base64 Encoder / Decoder handles both alphabets and won't choke on missing padding.