What to do when Base64 will not decode on a Mac
Work through these in order in B64. The first cause is the right answer roughly four times out of five.
You pasted a payload and got an inline note instead of a picture. The message sits beside the input rather than in a dialog, so you can fix the input and watch it resolve. Here is what to try, in the order the causes actually occur.
1. It was truncated
This is the answer most of the time. Base64 payloads are enormous and are copied out of soft-wrapped source views, chat messages and terminals that abbreviate long lines for display.
What to do: go back to the source and take all of it. In a browser's source view, use the element inspector's copy command rather than dragging a selection. If it came through a chat client, ask for a file instead — see exporting Base64 to a text file.
A complete Base64 payload has a length that is a multiple of four, usually ending in one or two = characters. A string ending abruptly mid-alphabet is a strong sign it was cut.
2. It decoded, but it is not an image
Valid Base64 can encode any file at all. If the characters were fine but nothing appears, the payload may be a zip, a text file, an audio clip or a data structure.
What to do: nothing is wrong with the payload. It simply is not a picture, and there is nothing for an image view to show.
3. Stray characters came along with it
Text that has travelled through a chat client, a word processor or a web form often picks up passengers:
- Curly quotation marks where straight ones were.
- An ellipsis where something was abbreviated for display.
- Zero-width characters that are invisible but real.
- A stray prefix or suffix — a quote, a bracket, a trailing comma.
What to do: get the payload as a file rather than as a message, or copy it again from the original source rather than from something that rendered it.
4. It uses the URL-safe alphabet
Standard Base64 uses + and /. A URL-safe variant swaps them for - and _ so the string can sit in a URL without escaping. They are different alphabets.
How to spot it: the payload contains hyphens and underscores but no plus or slash characters. What to do: ask the source for standard Base64, which is what a data URI requires in any case.
5. It is not Base64 at all
Hexadecimal is the usual impostor — a long string of 0-9a-f with no capitals and no punctuation. Base64 uses upper and lower case, digits, plus and slash. If everything is lower-case hex, it is a different encoding.
6. It is a fragment of something larger
A payload copied out of the middle of a multipart message, or one half of a string that was split across two fields, will not decode on its own. Base64 has to start at the beginning.
A quick diagnostic table
| What you see | Most likely | Do this |
|---|---|---|
| An invalid-Base64 note | Truncation | Copy the whole payload again, from the original |
| Decodes, but no picture | Not an image | Nothing — the payload is fine |
| Hyphens and underscores, no + or / | URL-safe alphabet | Ask for standard Base64 |
| All lower-case hex | Not Base64 | Check what encoding it really is |
| Works sometimes, fails when pasted from chat | Stray characters | Move it as a file instead |
| Decodes to a broken image | Truncation again | Compare checksums with the source |
When it decodes to a damaged picture
Half an image, or a picture with the bottom missing, means the payload was cut but happened to be cut at a valid boundary. The decoder had no way to know it was incomplete.
Confirm it with checksums: get the SHA-256 of the decoded bytes in the Inspector (⌥⌘I) and compare it against the source file's. See how to get the SHA-256 checksum of an image.
Things that are not the problem
- Line breaks. Wrapped payloads decode fine; whitespace is skipped.
- The data URI prefix. Leave it on — it is read, not choked on.
- HTML, CSS or Markdown around it. The payload is found inside.
- Size. Multi-megabyte payloads decode; they are just displayed in pages.
Frequently asked questions
Why will my Base64 not decode?
Truncation, most of the time. Base64 payloads are long and easy to cut short when copied out of a soft-wrapped source view or a chat message. Copy the whole thing again from the original.
Do line breaks stop Base64 decoding?
No. Whitespace is skipped, so wrapped payloads decode exactly like unwrapped ones.
What if it decodes but shows no picture?
The payload is valid Base64 of something that is not an image — a zip, a text file, anything. Nothing is wrong with it; there is just nothing to display.
What is URL-safe Base64?
A variant that uses hyphen and underscore instead of plus and slash so it can sit in a URL. It is a different alphabet, and a data URI needs the standard one.
How do I tell whether a decoded image is complete?
Compare the SHA-256 of the decoded bytes against the source file's checksum in the Inspector. A payload cut at a valid boundary can decode to a damaged picture without any error.