Base64 and Data URI Cheat Sheet: MIME and Pitfalls

Base64 is the plumbing of the web: JWTs, data URIs, email attachments, CSS-embedded fonts, API payloads. The encoding itself is simple — every 3 bytes become 4 characters from A–Z a–z 0–9 + /. The questions below are the ones that actually come up in a working session: garbage after decoding, the right MIME prefix, a JWT that refuses to decode, and whether to inline an image at all.

Data URI grammar at a glance

data:[<MIME type>][;base64],<payload>

data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
data:text/plain;charset=utf-8,Hello%20world
data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'...</svg>

• No ;base64 flag → the payload is literal text (percent-encoded where needed).
• With the flag → the payload is base64; the MIME type and charset parameter tell the browser how to interpret the decoded bytes.
• MIME type omitted → defaults to text/plain;charset=US-ASCII — the classic cause of "my inlined SVG renders as text".

The MIME prefixes you actually use

Those "recognizable starts" are the base64 of each format's magic bytes: iVBORw encodes PNG's \x89PNG, /9j/ encodes JPEG's \xFF\xD8\xFF, UklGR encodes WebP's RIFF, JVBERi0 encodes PDF's %PDF, and eyJ encodes {" — the universal first two characters of every JWT segment. Recognizing them makes decode errors diagnosable on sight: a payload that should be a PNG but starts differently means the MIME prefix and the payload disagree.

Padding and the URL-safe alphabet

• Padding: base64 output length is always a multiple of 4; = characters pad the final quantum. Some decoders require it, some tolerate its absence. When a decode fails with "invalid length", adding or stripping padding is the first check.
• base64url replaces + → - and / → _. JWT segments must also drop the = padding (RFC 7515 §3.2); other base64url uses may keep it. JWTs mandate the URL-safe alphabet; URL parameters should use it too. The Base64 Encode / Decode tool handles text conversions with both alphabets in mind, and the JWT Decoder applies the URL-safe alphabet per segment automatically.

The Unicode pitfall (JavaScript)

btoa throws InvalidCharacterError for any character above U+007F — which includes every CJK character and emoji. The string must be UTF-8 encoded to bytes first:

// Encode: text → UTF-8 bytes → base64
const bytes = new TextEncoder().encode(text);
const b64 = btoa(String.fromCharCode(...bytes));

// Decode: base64 → bytes → UTF-8 text
const bin = atob(b64);
const text = new TextDecoder().decode(Uint8Array.from(bin, c => c.charCodeAt(0)));

The historical one-liner btoa(unescape(encodeURIComponent(s))) does the same thing but leans on a deprecated function. Symptom of getting it wrong: é becomes é, CJK text becomes mojibake, and the round-trip is not stable.

Inline or separate file? A decision table

Quick recipes

// CSS: inline icon
background-image: url("data:image/svg+xml;base64,PHN2Zy4uLg==");

// HTML: inline image
<img src="data:image/png;base64,iVBORw0KGgo..." alt="logo" />

// JS: file → data URI (browser)
const uri = await new Promise((res, rej) => {
  const r = new FileReader();
  r.onload = () => res(r.result);
  r.readAsDataURL(file);
});

// CLI: file → base64
base64 -w0 image.png             # Linux (single line)
base64 -i image.png              # macOS (-i = input file; output is single-line by default)
certutil -encode in.png out.txt  # Windows

Convert and verify locally

The Base64 Encode / Decode tool handles text round-trips with full Unicode correctness, and the Image to Base64 Converter produces ready-to-paste data URIs and vision-API JSON snippets from real image files — both entirely in the browser, so nothing you encode is uploaded. A useful final check for any inlined asset: decode it back and compare the first bytes against the magic-number table above; a mismatch means the MIME prefix does not match the actual bytes — the usual "broken inline image" bug.