How-to guide

How to Fix Base64 Decoding Errors

A Base64 decode fails for four reasons. The string uses the URL-safe alphabet, where minus and underscore replace plus and slash. The padding equals signs were stripped. Line breaks or spaces were introduced by copying. Or the value was encoded twice, in which case decoding once returns more Base64 rather than an error. Check the alphabet first.

Base64 Encoder and Decoder

Encode text to Base64 or decode it back, including URL-safe.

Open the tool

Base64 has two alphabets and inconsistent opinions about padding, which is why a string produced by one system so often fails in another. Neither variation is a mistake; they are both legitimate, and a decoder that only understands one will reject the other.

The length is the quickest diagnostic. Standard Base64 always has a length that is a multiple of four, because every three input bytes become exactly four output characters. A length that is not a multiple of four means padding was removed.

Step by step

Look for minus and underscore
If the string contains - or _ it is Base64url, the URL-safe variant defined for use in URLs and JWTs. Replace - with + and _ with / before decoding, or use a decoder that accepts both alphabets.
Check the length against a multiple of four
Divide the length by four. A remainder of 2 means two = signs were stripped; a remainder of 3 means one was. Append them and decode again. A remainder of 1 is not valid Base64 at all and means characters are missing.
Strip whitespace and line breaks
Copying a long value out of a terminal or an email often introduces newlines. Some decoders tolerate them and some do not. Removing all whitespace is always safe, because whitespace is never meaningful inside a Base64 payload.
Decode once and look at the result
If decoding succeeds but the output is still Base64-looking text, the value was encoded twice. This happens when a system encodes a payload that a framework had already encoded. Decode again rather than treating the first result as corrupt.
Confirm the result is the type you expected
A successful decode that produces unreadable bytes is not necessarily a failure. Binary content — an image, a compressed archive, a protobuf message — decodes correctly and simply is not text. Check the first few bytes for a file signature before assuming it is broken.

Example

The same value in both alphabets. The URL-safe form has no padding and uses _ where the standard form uses /.

Base64url (as found in a JWT)

eyJhbGciOiJIUzI1NiJ9

Standard Base64, padded

eyJhbGciOiJIUzI1NiJ9
decodes to: {"alg":"HS256"}

Frequently asked questions

Why does my Base64 string fail to decode?

Most often because it is Base64url rather than standard Base64 — it will contain minus or underscore characters — or because the trailing equals signs were removed. Both are common in URLs and JWTs, where padding and the plus and slash characters cause problems.

Are the equals signs at the end required?

They pad the output to a multiple of four characters. Many decoders accept unpadded input, but strict ones do not. Adding the padding back is always safe, so it is the first thing to try when a decode is refused.

What is the difference between Base64 and Base64url?

Only two characters. Base64url uses minus instead of plus and underscore instead of slash, so the result can appear in a URL or a filename without escaping, and it usually omits padding. The encoded data is otherwise identical.

Why is my decoded output unreadable?

Because the original data was not text. Images, archives and binary protocol messages all Base64-encode perfectly well and decode back to bytes that a text view cannot display. That is a correct decode, not a failure.

Is Base64 a form of encryption?

No. It is an encoding, fully reversible by anyone, with no key involved. It exists to move binary data through text-only channels safely. Never use it to protect a secret.

Tools used in this guide

All tools →

All guides →

Last reviewed 28 August 2026.