How to fix a data URI that will not load on a Mac
Work through these in B64 in order. Each check rules out one cause, and the last step produces a URI you know is right.
A data URI is either completely right or completely invisible. There is no partial rendering and, in most consumers, no error message — the image is simply not there. Here is how to find out which of the four usual causes you have.
First: does the payload decode at all?
Paste the whole URI into Decode (⌘2). This splits the problem in two immediately:
- The picture appears. The payload is fine — the problem is in the URI's syntax or in the consumer. Carry on below.
- Nothing appears. The payload itself is broken. Go to what to do when Base64 will not decode.
Cause 1: a line break got into it
The most common cause of a URI that decodes here but shows nothing there. Formatters, editors and mail clients wrap long lines, and a newline inside a data URI invalidates it.
What to do: turn off hard wrapping for that file, or exclude it from your formatter. Then paste a fresh copy. This is also why the wrapping control is disabled on the data URI format — see line wrapping.
Cause 2: the prefix is wrong or missing
All four parts have to be there, spelled exactly:
data:image/png;base64,iVBORw0KGgo…
│ │ │ └─ the payload
│ │ └──────── the word "base64", with the semicolon before it
│ └────────────────── the MIME type
└─────────────────────── the scheme, with its colonThings that go wrong by hand: a missing comma, ;base64 left out, a space after the comma, or a smart quote where a straight one should be.
Cause 3: the declared type is wrong
The URI says image/png and the bytes are a JPEG. A browser sniffs and renders it anyway; a stricter consumer rejects it. That is why this bug so often “works on my machine”.
How to check: decode the URI and open the Inspector (⌥⌘I). It shows declared and actual side by side. See how to check the real format.
Cause 4: the consumer will not take it
Some places simply refuse data URIs, and no amount of correctness will change that. The usual ones:
- Markdown renderers that strip them for security.
- Content security policies that do not allow
data:as an image source. - Size limits in mail clients, databases and form fields.
- Formats the consumer does not support — a correct
image/heicURI in a place that cannot read HEIC. See converting HEIC.
The clean fix: produce a known-good URI
Decode what you have
Paste the URI into Decode and save the picture with Save…. It is written with the extension its bytes deserve.
Encode it again
Load that saved file into Encode (⌘1) and choose Data URI. The prefix is written from the actual bytes, the type is correct, and there are no line breaks in it.
Test it before you use it
Paste it into a browser address bar. If the picture appears, the URI is good — and anything that still refuses it is refusing data URIs, not yours.
A URI that renders in an address bar is syntactically complete and correctly typed. If it works there and not where you need it, the problem is a policy or a limit at the far end rather than anything in the string.
Quick reference
| Symptom | Likely cause |
|---|---|
| Works in a browser bar, not in your page | A content security policy |
| Worked before a save or a format run | A line break was introduced |
| Works in some clients, not others | Wrong declared type, or an unsupported format |
| Nothing anywhere, and will not decode here | Truncated payload |
| Works for small images, fails for large ones | A size limit at the far end |
Frequently asked questions
Why does my data URI show nothing?
Most often a line break inside it, or a truncated payload. Paste it into Decode first: if the picture appears there, the payload is fine and the problem is in the URI syntax or at the far end.
Can a data URI contain line breaks?
No. A newline invalidates it, which is why formatters and editors that wrap long lines break them so often.
Why does it work in my browser but not in the app I am targeting?
Usually a wrong declared MIME type — browsers sniff the bytes and render anyway, while stricter consumers check the declaration — or a content security policy that does not allow data: sources.
What is the quickest way to get a URI I know is correct?
Decode what you have, save the picture, encode the saved file again as a data URI, and test it in a browser address bar.