DEV Community: zbinze

URL-Safe Base64 vs Standard: How to Tell Them Apart

zbinze — Thu, 29 Oct 2026 01:36:41 +0000

Standard Base64 uses 64 characters: A–Z, a–z, 0–9, and then + and /. Those last two are the problem. In a URL, + means space in application/x-www-form-urlencoded; / is a path separator. In a filename, / is a directory separator. So a string that is perfectly valid Base64 becomes structurally dangerous the moment you put it in a query parameter, a cookie value, or a JWT.

The fix is an alphabet substitution, and it is where a surprising number of decoding failures begin.

The substitution, and the name it goes by

URL-safe Base64 — also called base64url, or RFC 4648 §5 — replaces the two troublesome characters:

+ becomes - (hyphen)
/ becomes _ (underscore)

Everything else is identical. Sixty-two characters are shared, so most strings are valid in both alphabets and decode to the same bytes. Only strings containing +, /, - or _ tell you which alphabet the producer had in mind.

Two of those four characters are ambiguous, which is the heart of the problem. If a string contains -, it is nearly certainly base64url. If it contains +, it is standard. But a string containing only [A-Za-z0-9] and = is valid in both, and there is no way to tell from the text alone. Decoding it either way gives the same answer, so ambiguity is harmless there.

The dangerous middle case is a standard Base64 string that happens to contain - or _... except it cannot, because those characters are not in the standard alphabet. Which means the rule is simpler than it looks: if you see - or _, treat it as base64url and convert; if you see + or /, treat it as standard. If you see a mix, the string is not valid in either alphabet and something upstream concatenated two different strings.

Padding, again

RFC 4648 §5 allows base64url to omit = padding, and most producers of JWTs and URL tokens do exactly that. The padding carries no information — it is determined by the length — so it is pure overhead in a token that will be embedded in a header.

This is why a raw JWT segment often has a length that is not a multiple of four:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

That is 36 characters, divisible by 4 by luck. A payload segment is often not. Strict decoders will reject it, so restore padding before decoding — it is deterministic and lossless:

const padded = s + '='.repeat((4 - (s.length % 4)) % 4);

Converting between the two

In JavaScript, browsers, and Node, the conversion is a two-character substitution in each direction, applied to the text form:

const toUrlSafe = (b64) => b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const fromUrlSafe = (s) => {
  const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
  return b64 + '='.repeat((4 - (b64.length % 4)) % 4);
};

Node has it built in, in both directions, on both buffers and strings:

Buffer.from(bytes).toString('base64url');        // encode
Buffer.from(token, 'base64url').toString('utf8'); // decode

Python calls it urlsafe_b64decode, and its counterpart is urlsafe_b64encode:

import base64
raw = base64.urlsafe_b64decode(token + '=' * (-len(token) % 4))

Note the asymmetry that catches people out: urlsafe_b64decode accepts both alphabets' characters in some versions, so it will not complain about a standard string containing +. It is forgiving in the direction where forgiveness is harmless, and strict about padding in the direction where being wrong matters.

Why a decoder should report the alphabet it used

If a string contains - or _ and you decode it as standard Base64, you get an error at the exact character that is out of range — which at least tells you something is wrong. But some decoders quietly translate the characters for you, and that is where the worst failure mode lives: a string that is actually standard Base64 containing a legitimate + or / gets mangled into the wrong bytes because the decoder assumed base64url.

For a picture, that means an image that decodes without error and will not render. For a JWT segment, it means a signature that fails to verify with no explanation.

That is why the decoder reports which alphabet it chose, and why a checkbox is offered to override it. Our URL-safe Base64 to Image page exists for the case where you know the source used the URL-safe alphabet and want it treated that way from the start, without guessing. When the input contains - or _ and the switch is off, the tool says so explicitly rather than silently picking one interpretation.

The practical rule

Three questions, in order:

Will this string travel through a URL, a filename, or a cookie? If yes, produce base64url. It costs nothing and removes an entire class of escaping bugs.
Does the string contain + or /? Treat it as standard Base64. Those characters cannot appear in base64url.
Does it contain - or _? Treat it as base64url.

And one habit worth building: never re-encode a string you received before decoding it. Converting a standard string to URL-safe form and back is lossless, but doing it speculatively — normalising before you know the alphabet — is how a + becomes a space in a query string and then becomes a different byte after decoding. Decode first, from the form you received, then re-encode in whatever form the next consumer needs.

The alphabet is only half of what makes a value safe to put in a URL. The other half is the characters around it, where an unescaped & or # splits the value with no error at all. Percent-encoding: the reserved characters that break URLs covers that half.

Where this shows up in practice

JWTs are the most familiar case: three base64url segments separated by dots, no padding, no line breaks. Their compactness is the whole point, and standard Base64 would break every one of them at the + and /.

Less obvious cases include opaque session cookies, signed URLs (AWS presigned URLs use standard Base64 in some parameters and URL-safe in others), correlation IDs in headers, and image payloads passed as query parameters in APIs that were never designed to carry binary data. In all of them, the failure looks the same: a string that "should decode" produces either an error at one character position, or bytes that decode cleanly and mean nothing.

The second outcome is the one to watch for. If you decoded something and the result is not the file or the payload you expected, check the alphabet before you check anything else — see Base64 image not showing for the full order of checks, which starts with exactly that question. If you would rather have the alphabet handled for you, the URL-safe Base64 to Image page treats - and _ as the expected alphabet from the start, and Base64 to Image auto-detects it while telling you which interpretation it used.

Why Card Number Formats Differ: Hex, Decimal, Byte Order

zbinze — Wed, 28 Oct 2026 01:35:13 +0000

A card holds a few bytes of opaque identifier. The number a reader shows you is a projection of those bytes — a base and a byte order chosen by whoever wrote the firmware — and nothing more. That is why the same credential can read as 04A2243A on the installer's laptop, 04:A2:24:3A on the controller, 77734970 in one database and 975479300 in another. Four correct answers, zero agreement.

Once the formats are seen as bytes plus two decisions — which base, and which end of the byte string is byte zero — the conversions stop looking like magic and start looking like a checklist.

A card UID is bytes; the number is a projection

125 kHz proximity cards and Mifare Classic carry a 4-byte UID. DESFire, Ultralight and many ISO 14443-4 cards carry 7 bytes; a handful carry 10. Those bytes are an identifier, not a quantity: there is no "true" decimal value for a UID, only the value some system computed from it.

The length of the number is therefore evidence. A decimal number above 4,294,967,295 (2^32 − 1) cannot have come from 4 bytes. A number above roughly 72,057,594,037,927,935 (2^56 − 1) cannot have come from 7 bytes. Those two bounds usually narrow the card family down before anything else has been looked at — and they are the reason a "16-digit decimal card number" is a contradiction unless the producer is printing something other than a raw UID, such as a printed credential number from a separate database column.

The forms, and how they relate

Take one card whose UID is 04 A2 24 3A:

bytes on the card      04 A2 24 3A
big-endian hex         04A2243A            ← the standard hex print
colon-grouped hex      04:A2:24:3A         ← the same bytes, readable
decimal (big-endian)   77,734,970          ← 04A2243A as a 32-bit integer
little-endian hex      3A24A204            ← the byte string reversed
reversed decimal       975,479,300         ← the reversal, as an integer

Read that list again, because it contains the whole problem: 77,734,970 and 975,479,300 are the same card. A system given the wrong one will accept nothing at all, or worse, accept a number that belongs to a different credential.

The two directions that appear in the wild are:

Big-endian (network order). The first byte is the most significant. This is what hex printing produces, what a printf loop over bytes produces, and what most access-control software stores.
Little-endian, reversed. The byte string is flipped before it becomes a number. This is what a large share of 125 kHz readers print, especially in Asia, which is why the number on the card holder's paperwork rarely matches the number in the controller.

The mapping is a byte reversal, not a digit reversal. Reversing 975,479,300 as digits gives 003,974,579, which is not a card at all; reversing the bytes gives 3A24A204, and reversing that gives back 04A2243A. A converter that reverses decimal digits has misunderstood the format, and the numbers it produces look entirely plausible.

Where the conversion invents a number

Three failure modes account for most "this card works on one door and not the other" reports.

Thousands separators. Copy a column out of Excel and you get the display text: 2,864,434,397, commas included. Split naively on commas and one card becomes two cells, 2 and 864,434,397 — and a converter that reports success has just produced two card numbers that do not exist. The correct reading is that 2,864,434,397 is one value (it is AABBCCDD in hex), and the correct behaviour for the ambiguous case is to refuse the input rather than guess. The judgement call is whether a comma is a thousands separator or a column delimiter; it needs a test, not a comment.

Leading zeros. A byte of 0x0A is 10 in decimal and 0A in hex — the leading zero survives in hex and disappears in decimal. A 4-byte UID whose first byte is 0x00 is legal, and it becomes indistinguishable from a 3-byte number the moment it is stored as an integer. Store UIDs as byte strings or as fixed-width hex, never as integers, or the first byte you lose will be the one that made the card unique.

Precision. A 7-byte UID does not always fit in a JavaScript Number. Number.MAX_SAFE_INTEGER is 9,007,199,254,740,992 (2^53), and any 7-byte UID whose first byte is 0x20 or above exceeds it. NXP-style UIDs that begin with 0x04 top out at 1,407,374,883,553,279 and stay inside the safe range by luck — a property of that one leading byte, not something to rely on. Parse the hex digits with BigInt when the field is 7 bytes wide:

const s = '461B6C44F53981';

parseInt(s, 16);                       // 19733400197085570  ← wrong
BigInt('0x' + s).toString(10);         // 19733400197085569  ← the card

The two values differ in the last digit, and the wrong one is not an error: it is a valid number that will enroll happily and never match the card again. That is the characteristic failure of this whole subject — a plausible wrong answer instead of a failure.

Parsing a column instead of a value

Real work arrives as a column pasted out of a spreadsheet, not as one clean string, and the column is rarely uniform: some rows decimal as the reader printed them, some hex with colons, some reversed. Guessing a format per cell is how half a table ends up wrong while the tool reports no failures at all.

What is needed is a converter that says which row it rejected and why. "Row 14: five colon-separated groups is not a 4-byte or 7-byte UID" is actionable; "invalid input" for 200 rows is not. The card number converter works that way by design: paste a column in any of the forms above and it shows every form of each value, refuses rows it cannot read unambiguously, and exports the table as CSV for whatever system needs it next. It reads the bytes and prints projections — it never rounds a projection back into bytes and calls the result the card.

When two systems disagree, check in this order

Length. 4 bytes, 7 bytes or 10? Half the hypotheses are eliminated by this alone.
Byte order. Reverse the bytes and compare again. If the reversed value matches, the disagreement is found and it is not a hardware fault.
Leading zeros. Compare the hex forms rather than the decimal ones; if one side is a byte short, that is the difference.
Base. 10000000 could be decimal, or hex, or a number that happens to look round. Compare as fixed-width hex before concluding that two systems hold different cards.
Frame, not UID. If the number came out of a Wiegand frame rather than being a raw UID, the split between facility code and card number is involved — see Wiegand 26 vs 34, where one credential legitimately becomes two different numbers.

While debugging, keep hex and Base64 apart. Hex is one character per nibble and is a representation of the bytes; Base64 is a different encoding with a four-for-three expansion, and a string that looks hexadecimal is not automatically hex — the comparison of hex, Base32, Base64 and Ascii85 covers how to tell them apart from the string itself.

The habit that prevents most of this: normalise on the way in, keep the bytes, and print only the form the receiving system asked for. Every extra round trip through a decimal integer is another chance to reverse something that was already reversed.

Percent-Encoding: The Reserved Characters That Break URLs

zbinze — Tue, 27 Oct 2026 01:43:42 +0000

A URL is not a string with escapes in it. It is a small grammar with several interchangeable parts — scheme, authority, path, query, fragment — and a character's meaning depends on which part it appears in. Percent-encoding exists so that data can be carried inside those parts without being mistaken for the grammar itself. When that goes wrong, nothing reports an error: the value simply arrives shorter, split in two, or pointing somewhere the server never sees.

The two sets, and one detail about them

RFC 3986 divides characters into two groups.

Unreserved — A–Z, a–z, 0–9, -, ., _, ~. These never need encoding, and encoding them anyway creates a second spelling of the same URL. That looks harmless until two spellings reach a cache, a signature calculation or a URL-based access rule, and are treated as two different resources.

Reserved, in two flavours:

gen-delims — :, /, ?, #, [, ], @
sub-delims — !, $, &, ', (, ), *, +, ,, ;, =

Reserved does not mean "always encode". It means "this character has a job here". : is a delimiter in the authority (host:port) and perfectly ordinary data in a path segment. & is a separator between query parameters and perfectly ordinary data inside a path. The rule is always relative to the component you are writing.

One detail that trips parsers: percent-encoded triplets are case-insensitive — %2F and %2f mean the same octet — but string equality in your code is not. Canonicalise to uppercase hex before comparing, hashing or signing, or two identical URLs will produce two different signatures.

The characters that cause incidents

& in a query value. The value ends at the &; everything after it becomes another parameter. Symptom: a long token arrives truncated at an arbitrary point, and an extra parameter appears in the request that no client intended to send.

# anywhere in a query value. Everything from the # onward becomes the fragment, and a browser never sends the fragment to the server. So the server sees the value cut at that point, and the browser's own address bar shows the rest — the single most confusing version of this bug, because the URL looks complete to everyone who inspects it locally.

+ in a query value. Under application/x-www-form-urlencoded rules it means a space, so C++ becomes C. In a path it is a literal plus. Send a literal plus as %2B if you want it to survive being handled by two different libraries.

% on its own. A literal percent sign must be %25. A single % followed by something that is not two hex digits makes the URL invalid, and strict parsers reject the whole thing rather than the character — which is why an input like 100% or %AB in a template can break an otherwise fine request.

Space. %20 in a path and in a standards-compliant query; + in form-encoded data. Both are widely accepted on the way in, and that mutual tolerance is precisely why the bug survives so long: it works with the parser you tested and fails with the one in production.

/ inside a path segment value. Encode it as %2F and the value no longer looks like two segments — but many servers decode the path before routing, so %2F is turned back into a separator and your value splits anyway. Some servers reject encoded slashes outright, and the reason is security: %2F and %2E are the building blocks of path traversal attempts, so proxies and application servers have strong opinions about them. The honest conclusion is that a value containing a slash does not belong in a single path segment.

? in a query value. Legal in a query by the grammar, and best encoded anyway, since a second ? invites a second round of parsing in intermediaries.

Non-ASCII is bytes, not characters

This is where percent-encoding stops looking like an escaping scheme and starts looking like an encoding.

A %XX triplet carries one byte, not one character. A character outside ASCII has to be turned into bytes first, and the only interoperable choice is UTF-8:

é is U+00E9, two bytes in UTF-8 (C3 A9), so it encodes to %C3%A9.
A CJK character such as U+4E2D is three bytes (E4 B8 AD), so it encodes to %E4%B8%AD — nine characters to carry one.

If the producer used a different legacy encoding, the triplets are still perfectly well-formed and still decode to something — just not to the text that was sent. A GBK-encoded Chinese string arriving at a UTF-8 decoder produces a page of replacement characters, and nothing in the request looks wrong. So "the encoding is valid" and "the characters are correct" are separate questions, and the second one needs the producer's encoding to be known.

The related rule for implementers: always percent-encode bytes, never code points and never characters. In languages where a string is a sequence of UTF-16 code units, encoding a character directly is how astral-plane characters get written as surrogate halves, which no decoder will accept.

A decoder should refuse, not guess

Decoding is where the damage becomes permanent, because a decoder that is generous with invalid input turns a visible bug into a plausible value.

An incomplete triplet at the end of the input (%E4%B8) is invalid. Truncating it silently produces text that is almost right.
An invalid UTF-8 byte sequence must be an error. Substituting U+FFFD without saying so means the caller never learns that the sender used the wrong encoding — and a value with a replacement character in it can be stored, indexed and passed along for years.
Over-long encodings — the historical trick of writing / as %C0%AF — must be rejected rather than decoded to the shorter form, since that is precisely what makes them dangerous in a security context.
A % that is not followed by two hex digits is a malformed URL. Reporting it as malformed is more useful than treating % as literal, because the caller then finds the template that forgot to escape.

A decoder that does the opposite — normalising, repairing and reporting success — is the reason two systems can disagree about the same URL while both claim to have decoded it. The strict-but-explicit behaviour is what the URL encoder and decoder implements: it shows which characters it changed, keeps UTF-8 byte handling separate from the text, and points at the exact position of a malformed sequence instead of quietly dropping it.

The rules worth keeping

Encode per component, not per URL. &, =, # and + are data in one part and syntax in another.
Never decode twice. %2520 is a percent sign followed by 20, not a space; if a second decode "fixes" it, the producer double-encoded, and that is their bug to fix.
Compare canonical forms: uppercase hex triplets, no needlessly encoded unreserved characters, one spelling per resource.
Treat non-ASCII as UTF-8 bytes and say so explicitly; where the sender's encoding is unknown, ask rather than assume.
Prefer refusing malformed input to repairing it — this is the difference between a decoder and a data corruption device.

The comparison with Base64 covers which of the two layers a given payload needs; when the payload is a token that must survive a query string untouched, the URL-safe alphabet is usually the better starting point than escaping your way out of an alphabet that already contains + and /.

Wiegand 26 vs 34 Bit Format: The Facility Code Split

zbinze — Mon, 26 Oct 2026 01:56:48 +0000

Wiegand is a wire, not a card format. A reader sends bits to a controller over two lines — DATA0 pulses for zeros, DATA1 pulses for ones, roughly 100 microseconds each with about a millisecond between them — and the controller reconstructs a number from the pulse count. No clock line, no packet length, no checksum. The "26" and "34" in Wiegand 26 and Wiegand 34 are simply the number of bits in that burst.

The part that causes trouble is what happens inside those bits. A frame carries a facility code, a card number, and two parity bits, and where the boundary between the two fields sits is a vendor convention, not something the frame declares. Two systems can read the same card, over the same wire, and disagree about who it is — with no error anywhere.

The frame, bit by bit

Wiegand 26   [P][ facility 8 bits ][ card number 16 bits ][P]
Wiegand 34   [P][ facility 16 bits][ card number 16 bits ][P]

             P = parity, one bit on each end of the frame

The 26-bit layout, used by HID H10301 and most 125 kHz proximity installations, is:

bit 1 — even parity over bits 2–13
bits 2–9 — facility code, 8 bits, 0–255
bits 10–25 — card number, 16 bits, 0–65,535
bit 26 — odd parity over bits 14–25

The 34-bit layout — HID H10306 and the AWID 34-bit credentials that share its shape — moves the boundary a long way:

bit 1 — even parity over bits 2–17
bits 2–17 — facility code, 16 bits, 0–65,535
bits 18–33 — card number, 16 bits, 0–65,535
bit 34 — odd parity over bits 18–33

So the card number is the same size in both. Everything the extra eight bits buy goes into the site field: 34-bit raises the number of distinct facility codes from 256 to 65,536. That is the whole difference, and it is the reason a site with more than 256 doors, tenants or buildings eventually migrates.

Why the boundary cannot be guessed

The frame length is agreed; the division is not. The same total can be split differently by different product families — 36-bit is a 17/17 site-and-card split in one, and an 8-bit site code with a 16-bit card number at entirely different bit offsets in another — and 34-bit credentials exist that use the same 16/16 shape but treat the site field as an issuer code rather than a facility code. Nothing in the transmission records which convention was used, which has a blunt consequence:

A controller configured for the wrong layout does not fail. It produces a different, valid number.

Feeding a 34-bit credential to a controller configured for 26 bits is the perfect example. The parser takes the first 26 bits of the burst: bit 1 becomes its even-parity bit, bits 2–9 become an 8-bit facility code that is really the top half of a 16-bit one, and bits 10–25 become a card number that is really the bottom half of the facility code followed by the top half of the real card number. The last eight bits of the frame, including the frame's own odd-parity bit, arrive after the parser has stopped reading. Almost always the parity check fails, the reader looks broken, and the card is perfectly fine.

The practical version of this, which turns up far more often than a hard failure, is a silent mismatch: a split that parses, passes parity and identifies a different person. With only 16 bits of card number, collisions are not theoretical. A site that has enrolled more than 65,535 credentials, or that reuses numbers across facility codes the panel can no longer see, ends up with two cards that are the same person to the controller — and the log will show a legitimate number for the wrong door.

Parity is the entire error-detection budget

Two parity bits over a 32-bit payload is a thin defence, and it is worth knowing exactly how thin.

Even parity over bits 2–13 means the twelve data bits plus the parity bit contain an even number of ones. If one pulse is dropped — a barrier motor starting up next to an unshielded run of cable is the classic cause — the bit count changes and the parity check fails. If two pulses are lost inside the same parity window, the count is even again and the frame passes. Wiegand has no way to notice, because there is nothing else in the frame to cross-check against: no length field, no sequence number, no CRC.

This is also why parity is computed over halves of the frame rather than the whole payload. Two 12-bit windows catch error patterns that one 26-bit window would not, at the cost of the two bits themselves. It is a 1950s answer to a 1950s problem, and it survives because the alternative — a bidirectional protocol — requires wires that the installed base does not have.

Reading a number out of a frame

Once a controller has the frame, the number it stores is the card number field, usually printed as decimal. That is where card-number formats start to blur: the same credential may be printed by one tool as a 26-bit decimal card number, by another as the raw hex of the whole frame — hex being a 1:1 representation of the bytes rather than an encoding, as the comparison of hex, Base32, Base64 and Ascii85 sets out — and by a third as a UID in reversed byte order. If the numbers you have in hand do not line up, the field boundary and the byte order are separate questions — Card Number Formats Explained walks the order to check them in, and the card number converter will show every form of a value you paste in, including the reversed reading that explains most "the system has the wrong number" tickets.

One useful sanity check before any of that: a 26-bit card number cannot exceed 65,535. If the number in your database is larger, it did not come from a 26-bit card number field — it came from a raw UID, a 34-bit-plus layout, or a mis-split frame.

When you want the frames computed rather than explained, the Wiegand 26/34 converter takes a whole frame, a hex payload, a facility-code pair or a bare card number and shows both widths side by side — including the parity check that tells you whether a captured frame survived the wiring.

You cannot convert 26 to 34

There is no arithmetic that turns a 26-bit credential into a 34-bit one, because nothing is being computed — a field boundary is being moved. Two honest options exist:

Reconfigure the panel to the format the credentials already use. This is a controller setting, and it is the cheap path when the reader, the cards and the panel all support the layout you are switching to.
Re-enroll the credentials into the new split, which means re-issuing or re-reading every card and rebuilding the access lists.

What does not work is "converting" the numbers: mapping a 900-series card number into a different facility code produces a credential that no card in the building carries. If a migration is on the table, the audit worth doing first is a count of distinct facility codes and the highest card number in use — those two numbers decide whether 34-bit is needed or merely convenient.

The security footnote that outlives the format

Wiegand is one-directional and unauthenticated. The reader talks; the controller listens; nothing is encrypted, and a facility code is printed on the card and known to anyone who has ever ordered credentials. 125 kHz proximity cards are also trivially clonable with commodity hardware, and because card numbers are usually sequential, an attacker who captures one frame has a good guess at its neighbours.

None of that is fixed by moving to 34 bits — it is fixed by replacing the protocol, which is what OSDP does: bidirectional, with a secure channel and encryption, so a reader can be authenticated and a cloned card alone is not enough. The reason 26-bit is still everywhere is not that it is good; it is that the wire, the readers and the doors are already installed, and the format travels with them.

If you are debugging a credential that reads differently on two systems, start with the bit split and the byte order — in that order. The frames are not lying; they are answering a slightly different question than the one being asked.

Base64 Image Not Showing? Six Checks, Cheapest First

zbinze — Sun, 25 Oct 2026 00:09:01 +0000

A Base64 image that will not display is one of the least informative failures in web development. You get a broken-image icon, or an empty box, or nothing at all — and the browser console is silent. There is no exception to catch, because the browser did exactly what it was told: it tried to render a resource and gave up quietly.

The good news is that there are only six realistic causes, they are cheap to check in order, and each one produces a different symptom if you look closely.

Check 1: is the string actually Base64?

Before anything else, establish that the payload is in the right alphabet. Two count-based checks catch most of it:

const payload = s.includes(',') ? s.slice(s.indexOf(',') + 1) : s;
console.log('length % 4 =', payload.length % 4);                        // 1 means truncated
console.log('illegal =', (payload.match(/[^A-Za-z0-9+/=_-]/g) || []).join(''));

A remainder of 1 is fatal: no complete Base64 string can produce it, so characters were lost in transit. Everything else can usually be repaired. Illegal characters tell you what went wrong — a newline means MIME wrapping (see line breaks and padding), a %3D means the string went through a URL, and a - or _ means it is URL-safe Base64 (see URL-safe vs standard).

If the string is full of 0-9a-f and nothing else, it is hexadecimal. Decoding it as Base64 will produce bytes without error, and those bytes will not be an image.

Check 2: is the prefix complete?

The syntax is data:[<mediatype>][;base64],<data> and all three parts are load-bearing. Three prefix bugs produce three different symptoms:

No ;base64 flag. data:image/png,iVBORw0KGgo... makes the browser read the payload as literal text. You get an empty image box and no error, because you asked for a text file.
No comma. data:image/png;base64 followed by the payload is not a data URI at all. If your code strips "everything up to the first comma", the strip silently does nothing and the decoder chokes on the : in the header.
A ;base64 typo such as base64; or ;base-64. Same as the first case: the payload is treated as text.

In a strict decoder these all fail loudly at a specific character position. In a browser they fail silently. That asymmetry is worth remembering when debugging: the browser is the least helpful place to ask "why".

Check 3: did it decode to any bytes at all?

A zero-byte result is a real outcome, and it has a specific cause: the payload contained nothing but padding characters, or the normalisation step removed everything it considered junk. Print the decoded length before you attempt to render:

const bytes = Uint8Array.from(atob(clean), (c) => c.charCodeAt(0));
console.log(bytes.length);   // 0 → nothing to render, however good the string looks

If the length is in the hundreds of kilobytes, you have data. Whether it is an image is Check 4.

Check 4: are the bytes an image — and the right one?

This is where the declared media type gets tested against reality. Read the first bytes and compare:

89 50        PNG
FF D8 FF     JPEG
47 49 46 38  GIF
52 49 46 46  WebP (with "WEBP" at offset 8)
1F 8B        gzip — not an image
25 50 44 46  PDF
50 4B 03 04  ZIP

Two distinct failures live here. The first is that the bytes are not an image at all — gzipped JSON that was Base64-encoded to move it through a text-only channel is the classic case, and it is worth naming explicitly because "it decoded fine" makes people stop looking. The second is that the bytes are an image but a different one from what the header claims: data:image/jpeg;base64,iVBORw0KGgo... renders in most browsers, then fails in every tool that trusts the declared type. The bytes win in both cases, which is why our Base64 to Image tool prints the declared type and the signature side by side instead of picking one.

Check 5: is the image complete?

This is the cause people miss, and it produces the most confusing symptom: the image does display, then stops halfway. A grey band across the bottom of a photo, or a picture that renders correctly in a browser but is rejected by an image editor.

The reason is that JPEG has no total-length field in its header. A JPEG truncated at any point still looks like a perfectly valid JPEG as long as the markers parsed so far were legal, so decoders render what they have and stop. Truncation is common because Base64 travels through places that truncate: log lines with length caps, terminal selection that drops a wrapped line, database columns sized for the average case, chat messages with attachment limits.

The test is arithmetic, not visual:

Decode the string and record the byte count.
Compare it with the size the source reports for the original file.
If the decoded count is lower, you have a truncated copy — go back to the source rather than trying to repair it.

For PNG the same check works, and there is an extra structural signal: a complete PNG ends with an IEND chunk. Reading the last twelve bytes and looking for 49 45 4E 44 (IEND) is a cheap completeness test:

const tail = bytes.subarray(-12);
console.log(new TextDecoder().decode(tail).includes('IEND'));

Check 6: is the browser refusing it for a reason unrelated to Base64?

The last two causes have nothing to do with the string, which is exactly why they are missed.

Content Security Policy. If your page sends img-src 'self' without data:, every data URI image is blocked — silently, and with no Base64 problem anywhere. The browser reports the violation to the console in most cases, but only if you know to look there, and tools that inject their own CSP by default (static hosts, reverse proxies) can add this without you noticing. Our own pages ship img-src 'self' blob: data: precisely for this reason.

Size. Data URIs are string data and live inside whatever document contains them. Very large ones — a few megabytes of Base64 in an inline <style> or a generated HTML file — hit parser and memory limits that vary by browser, and the failure looks like nothing at all happening. If a 40 KB icon works and a 4 MB photo does not, this is your answer, and the fix is a real URL instead.

The order matters

Run the checks in this order and stop at the first failure, because the later ones produce misleading results when the earlier ones are broken: a truncated string appears to "decode fine" and a wrong alphabet produces bytes that look like a corrupt image. Six checks, roughly a minute of work, and each one tells you a different thing to fix.

When you have the answer, the two repairs worth knowing are both structural rather than textual: pad the string if the remainder says it is short (safe, reversible), and go back to the source if the remainder is 1 or the decoded length does not match what the producer reported (not safe, not reversible, do not guess). Anything else — re-encoding, "trying" a different alphabet, appending bytes until it renders — is guessing at data you cannot see.