DEV Community: zbinze

URL Encoding vs Base64: When to Use Which

zbinze — Sat, 14 Nov 2026 06:07:50 +0000

Both percent-encoding and Base64 turn input into a restricted set of ASCII characters, both are reversible, and both are routinely described as "making a string safe". They are also answers to completely different questions, which is why choosing between them by feel produces data that survives the round trip in testing and falls apart in a log file three weeks later.

The distinction is one sentence long: percent-encoding protects characters that have syntactic meaning inside a URL, and Base64 re-encodes bytes that are not text at all. Get that backwards and nothing throws an exception — the value simply arrives different, or half of it arrives.

The rule, stated once

If what you have is text that must sit inside a URL component (a search term, a filename, a redirect target), percent-encode it for that component.
If what you have is bytes (an image, a hash, an encryption key, a protobuf), Base64 them — and then percent-encode the Base64 if it has to travel in a URL.

The second clause is the one people skip, and it is the source of the classic bug covered below. The two transforms compose; they do not compete.

What each one actually guarantees

Percent-encoding is defined per component of the URL grammar. It says: replace the bytes that are not allowed here with % followed by two hex digits. Its output is still text with the same meaning — a human can read an encoded path and see what it was. Its cost is unbounded in the worst case: an ASCII character costs one %XX triplet if it needs escaping (three characters), and a character outside ASCII costs one triplet per UTF-8 byte, so a single CJK character is nine characters.

Base64 is defined over bytes, with no knowledge of URLs. Its output uses 64 characters — A–Z, a–z, 0–9, +, / — plus = padding, and it expands by exactly one third. All of those characters are legal in a URL as characters, which is exactly why Base64 breaks there: + means something else, / means something else, and = is used by other parts of the URL syntax. Legal, and load-bearing, are not the same property.

The failure everyone hits: Base64 in a query string

Take an image encoded as standard Base64 and dropped into a query parameter:

https://example.test/img?data=iVBORw0KGgoAAAANSUhEUg...+/8AAAAASUVORK5CYII=

Every character there is legal in a URL, so the browser sends it and the server receives it. Then the server parses the query string with application/x-www-form-urlencoded rules — which is what most frameworks do by default — and in those rules + means a space. The Base64 that arrives is not the Base64 that was sent. If it decodes at all, it decodes to different bytes; more often it fails at a length that is not a multiple of four, at a totally different character position from the one that was altered.

There are two correct fixes, and they are not interchangeable:

Percent-encode the Base64 before appending it, and decode in the reverse order on the way back. + becomes %2B, which form parsing leaves alone.
Use the URL-safe alphabet — - and _ instead of + and / — which removes the ambiguity at the source rather than escaping around it. That alphabet, and where it comes from, is covered in URL-safe Base64 vs standard Base64.

The order of operations is worth writing down, because it is easy to get one step wrong and hard to see: bytes → Base64 → percent-encode → query string, and in reverse query string → percent-decode → Base64-decode → bytes. A percent-decode after a Base64-decode is a bug that only shows up on inputs containing %.

encodeURI vs encodeURIComponent

JavaScript offers both, and the difference is exactly the "per component" rule.

encodeURIComponent('a&b=c d');        // 'a%26b%3Dc%20d'
encodeURI('https://x.test/?a&b=c d'); // 'https://x.test/?a&b=c%20d'

encodeURI is designed to take a whole URL you already assembled. It therefore leaves &, =, ?, / and : alone — they are the URL's structure, and encoding them would destroy it. Used on a value that is then pasted into a query parameter, it leaves the & alone, and the & splits your value into a second parameter. That is a straightforward injection: user text becomes URL syntax.

encodeURIComponent is designed for one piece of a URL, so it encodes everything structural. It is the function to reach for by default, and one of the few places a rule of thumb is genuinely correct: if you are not certain, encode harder — an over-encoded unreserved character is harmless, an under-encoded & is a parameter injection.

Note also what encodeURIComponent does not encode: ! ' ( ) * - . _ ~ and alphanumerics are left as-is, because RFC 3986 marks them as unreserved. That is correct, and it is why two different producers can emit different-looking but equivalent strings — a fact that matters later, when a signature or cache key is computed over one of them.

Plus and space, the rule behind the folklore

+ meaning space is not a URL rule. It is a rule of application/x-www-form-urlencoded, the format used by HTML forms and, by convention, by query strings on many servers. Consequences worth knowing:

In a query string, + is usually read as a space. In a path, it is a literal plus. So ?q=C%2B%2B and ?q=C++ are different on a standards-compliant parser, and %2B is the only reliable way to send a literal plus in a value.
encodeURIComponent produces %20 for a space, not +. new URLSearchParams({ q: 'a b' }).toString() produces q=a+b — same meaning, different spelling. Both decode correctly under a form parser; neither decodes correctly under a strict URL parser that treats + literally. Which one you get is decided by the library, not by you, which is why round-tripping a value through two libraries is a reliable way to grow an extra space.
When a value is already encoded and you encode it again, spaces and + do not survive a naive double transform. That is the topic of percent-encoding: the reserved characters that break URLs, which goes through the character-level rules this section summarises.

When neither belongs in a URL

Both transform encodings cost something, and neither is a solution to "the URL is too long". Percent-encoding can triple the length of ASCII input and worse for non-ASCII; Base64 adds a flat 33% and then gets percent-encoded, so a binary payload in a URL can end up nearly twice its size in characters before anything else is counted — see why Base64 costs 33% for the arithmetic.

Practical limits are the reason this matters: older browsers capped URLs near 2,083 characters, many servers and proxies cap the request line at 8 KB, and every URL ends up in logs, analytics and referrer headers, where a megabyte of encoded data is not something anyone wants to retain. If the payload is more than a token or a short parameter, it belongs in the request body, not in the query string. If it is binary and it must be in a URL — a signed thumbnail, an inline data URI — that is a design decision with a cost, and Base64 plus percent-encoding is that cost. If you want to see where that cost lands, decode the data URI back into an image — the decoded byte count is printed next to the payload you pasted.

The decision list

User text going into a URL component → encodeURIComponent, or the equivalent in your language.
An assembled URL that needs non-ASCII or spaces escaped → encodeURI, knowing it leaves structure intact.
Binary going through a text channel → Base64; if the destination is a URL, use the URL-safe alphabet or percent-encode the result.
Text going into a form field or a body → percent-encode only if the field is defined as URL-encoded; otherwise send it as-is.
Anything large → the body, not the URL.
Base64 inside a JSON string inside a URL — the case that catches everyone twice — encode the Base64 first, then the JSON, then the URL component, and decode in exact reverse. The URL encoder and decoder shows the character-by-character result of each step, which is the fastest way to see which layer is eating your +.

"MIFARE Classic Sector Dump: What the Hex Actually Says"

zbinze — Fri, 13 Nov 2026 01:47:52 +0000

A card dump is the only description of a credential that does not depend on trusting somebody's reader. Every other form — the number printed on the card, the value the panel shows, the frame on the wire — has already been through a conversion that somebody chose. The dump has not. It is the bytes as they sit in the card's memory.

That also makes it the form people misread most often, because nothing in it is labelled and three of its conventions run against intuition.

The 1K layout, in one paragraph

A MIFARE Classic 1K card holds 1024 bytes, organised as 16 sectors of 4 blocks, and each block is 16 bytes. Blocks are addressed from 0 to 63. In every sector, the last block is special: block 3 of sector 0, block 7 of sector 1, block 11 of sector 2, and so on. Data lives in the other three blocks of each sector; the fourth holds the keys and the permissions for that sector.

So a full dump is 64 lines of 16 bytes if your tool prints one block per line, or 1024 bytes of continuous hex if it does not. When a dump arrives as one long string with no line breaks, the first thing to do is re-split it at 16 bytes — otherwise every offset you compute from it will be wrong, and wrong in a way that still produces plausible-looking numbers.

Sector 0, block 0 is not like the others

The first block of the first sector is the manufacturer block, and it is read-only. Its bytes are laid out roughly like this:

bytes 0 to 3 (or 0 to 6, or 0 to 9): the UID
the byte after the UID: the BCC, a checksum computed as the XOR of the UID bytes
the next byte: SAK
the next two bytes: ATQA
the rest: manufacturer data

Two consequences follow. First, you cannot change a card's UID by writing to it — that block refuses writes, which is why "UID changeable" cards are a separate product with a different chip inside, not a setting. Second, a 4-byte UID and a 7-byte UID produce different layouts inside the same block, so a script that hardcodes offsets 0 to 3 will read a 7-byte card's UID as "the first four bytes" and silently drop three.

The UID is stored backwards

This is the part that costs people the most time. MIFARE stores the UID least significant byte first, while most readers, panels and printed card numbers show it most significant byte first. A card whose dump begins E1 5A 3C 04 is the card a reader calls 043C5AE1.

Anyone who has compared two readers already knows this failure mode from the other direction — see why card number formats differ for the same problem in decimal and in 125 kHz readers. The dump does not have a convention of its own; it simply preserves the chip's byte order, and every layer above it may or may not reverse that order before showing you a number.

The BCC byte is a useful check here. XOR the UID bytes together and compare: if the result does not match the byte following the UID, either the UID length is not what you assumed, or the dump is not the block you think it is. It is a one-line check that catches the most common misreading.

The trailer block is three fields, not one

The last block of each sector contains, in order: 6 bytes of Key A, 4 bytes of access bits, 1 general-purpose byte, and 6 bytes of Key B. That is 17 fields' worth of meaning packed into 16 bytes, and the reason a "key" is never a 16-byte value no matter how often it is described that way.

Three things surprise people here:

Keys cannot be read back. The card will tell you whether a key is correct, and nothing else. A dump therefore never contains the keys in the sense of revealing them — the tool that produced the dump either already knew them or the sector is showing its factory defaults.

The access bits are stored three times. The four bytes hold the permission bits plus two inverted copies, so that a single flipped bit can be detected rather than obeyed. That is why the same configuration shows up as FF 07 80 in almost every tutorial: it is not a magic constant, it is one particular set of permissions written into all three copies.

A factory-fresh card is recognisable. When a sector has never been configured, its trailer usually still reads FF FF FF FF FF FF FF 07 80 69 FF FF FF FF FF FF. If you see that in a sector you expected to be in use, the card has not been personalised — or somebody reset it, which for a credential is worse news than a wrong number.

The 4K cards break the pattern

A 4K card is not "1K times four". It holds 4096 bytes in 40 sectors: sectors 0 to 31 are four blocks each, exactly like the 1K layout, and sectors 32 to 39 are sixteen blocks each. Block numbering continues past 63 instead of stopping there, and the trailer of a 16-block sector is block 15 of that sector, not block 3.

Any code that assumes "16 sectors" or "the trailer is at index 3" works perfectly on the card it was tested with and produces quietly wrong results on the other one. That is the same failure shape as reading a 34-bit credential with a 26-bit parser: no error, just a different and entirely plausible answer.

Three readings to distrust

A number that looks clean. If a UID reads as a round decimal or a familiar pattern, check the byte order before believing it.
A dump shorter than you expected. Truncated dumps are common; a 1K card is 1024 bytes and a 4K card is 4096, so count before analysing.
A sector with no trailer. If your dump has 15 bytes in a block, the tool dropped one and every offset after it has shifted.

To settle the first of those three, flip the byte order and compare: paste the UID in whichever reading your dump uses and the page prints both, each labelled with how it was read, so a reversed match is visible instead of inferred.

Where this connects to the wire

The dump is the card side; the Wiegand frame is the wire side, and the two disagree in ways that matter. A panel often stores only the low bytes of a UID, or converts it through a facility-code layout that was designed for a different card generation. When a card "works everywhere except one door", the useful comparison is dump bytes against frame bits — not the numbers printed on two different screens.

If you also have a file whose type you are inferring from its first bytes, reading signatures covers the same discipline for a different kind of binary: the first bytes are evidence, and the extension is not.

Image File Signatures: PNG, JPEG, WebP, AVIF and More

zbinze — Wed, 11 Nov 2026 01:43:07 +0000

Give a decoder three things — a filename ending in .png, a header saying image/jpeg, and a byte stream that starts with FF D8 FF — and only one of them is worth trusting. The extension is a naming convention that survives any rename. The declared MIME type is a claim written by whoever produced the data, and it is wrong often enough that treating it as fact is how you end up with a file that opens in your browser and breaks in every other tool.

The byte stream is the only part that cannot lie, because those bytes are what a decoder has to draw.

What a signature actually is

Every container format begins with a fixed pattern so that readers can identify it without parsing the whole file. The pattern is at a known offset — usually byte 0, sometimes byte 4 — and it is short: two to twelve bytes.

PNG    89 50 4E 47 0D 0A 1A 0A     then an IHDR chunk
JPEG   FF D8 FF                     then a segment marker
GIF    47 49 46 38   ("GIF8")       then 39 or 37 for version
WebP   52 49 46 46 __ __ __ __ 57 45 42 50    ("RIFF" size "WEBP")
BMP    42 4D         ("BM")
TIFF   49 49 2A 00 (little-endian) / 4D 4D 00 2A (big-endian)
ICO    00 00 01 00
AVIF   66 74 79 70 at offset 4, major brand "avif"
HEIC   66 74 79 70 at offset 4, major brand "heic" or "mif1"
JP2    00 00 00 0C 6A 50 20 20 0D 0A 87 0A
PSD    38 42 50 53  ("8BPS")

Two details in that list explain most of the confusion people run into.

The first is that PNG's signature contains 0D 0A — a CRLF — and 1A, a DOS end-of-file marker. Both are there deliberately: they were chosen in the 1990s so that a PNG file transferred through a text-mode FTP connection would be visibly corrupted rather than silently mangled. It is also why a PNG's first bytes look like text control characters in a hex dump.

The second is that AVIF, HEIC and HEIF share the same container. They are all ISO base media files, so all of them begin with an ftyp box; what distinguishes them is the four-character brand at offset 8. A decoder that only checks for ftyp will happily report "HEIC" for an AVIF file. This is why a correct implementation returns a ranked list of candidates rather than one answer, and why our Base64 to Image tool reports the evidence (ftyp box + major brand "avif") instead of just a format name.

Reading the bytes in JavaScript

Four lines, no dependencies. Take the first twelve bytes after decoding and compare them:

const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const head = bytes.subarray(0, 12);

const eq = (offset, ...sig) => sig.every((b, i) => head[offset + i] === b);
const ascii = (offset, len = 4) => String.fromCharCode(...head.subarray(offset, offset + len));

if (eq(0, 0x89, 0x50, 0x4e, 0x47)) return 'image/png';
if (eq(0, 0xff, 0xd8, 0xff)) return 'image/jpeg';
if (eq(0, 0x47, 0x49, 0x46, 0x38)) return 'image/gif';
if (eq(0, 0x52, 0x49, 0x46, 0x46) && ascii(8) === 'WEBP') return 'image/webp';
if (ascii(4) === 'ftyp') {
  const brand = ascii(8);
  if (brand === 'avif' || brand === 'avis') return 'image/avif';
  if (brand === 'heic' || brand === 'heix' || brand === 'mif1') return 'image/heic';
}
return null;

Note what happens after the signature check: head is only the first twelve bytes, so this identifies the container, not the contents. A signature says "this is a PNG stream", never "this PNG is complete". Those are different questions, and conflating them is behind a large share of "the file looks fine but the image is half grey" reports — JPEG in particular has no total-length field in its header, so a truncated JPEG still looks like a perfectly legal JPEG for the first few kilobytes.

The four impostors you will actually meet

When a decoder reports "not an image", the more useful question is what is it. In practice, four families account for almost everything that arrives where a picture was expected.

Compressed archives. 1F 8B is gzip, 78 9C is a zlib stream, 50 4B 03 04 is a ZIP entry, 50 4B 05 06 is an empty ZIP's end-of-central-directory record. Gzipped JSON that someone Base64-encoded to move it through a text channel lands here, and it is by far the most common cause of this report.
Documents. 25 50 44 46 is %PDF. A PDF that a browser previews inline is easy to mistake for an image when you only see a thumbnail.
Executables. 7F 45 4C 46 is ELF, 00 61 73 6D is a WebAssembly module, FF FE or FE FF at offset 0 indicates UTF-16 text.
Text that was already encoded. A string of 0-9a-f is hexadecimal, not Base64 with unusual characters. Decoding hex bytes as Base64 produces plausible-looking garbage instead of an error, which is why the distinction matters: the fix is to parse it as hex, not to keep re-encoding it.

Telling someone "it decoded to 200 KB but the bytes are gzip" is a different, and much more useful, statement than "invalid input".

Why a signature check belongs before the `<img>` element

If you assign decoded bytes to an <img> and the format is wrong, the browser fails silently: a broken-image icon, an error event, and nothing in the console. No exception, no diagnostic. A signature check converts that silence into a sentence, and it costs microseconds because it reads twelve bytes.

To do it by hand on a file you already have, drop the file and read its first bytes — the page prints the signature, the type the name claims and whether the two agree, and the file never leaves the browser.

The same check is what makes it safe to accept raw strings with no data: prefix at all — see the raw string decoder — because the format can be established from the bytes rather than from a header that may not exist.

It is also the check that turns a silent failure into a sentence. When a payload decodes but the format is wrong, the useful output is not "invalid image" but "these bytes are gzip"; Base64 image not showing walks through that decision order, and decoding in Python, Node and the browser covers the runtime differences you hit while getting the bytes in the first place.

One caveat about offsets: they are byte offsets into the decoded stream, and Base64 decoding has to be finished first. Whitespace, line breaks and padding in the encoded form do not shift anything after decoding, which is exactly why stripping them first is safe. If you try to reason about signatures on the Base64 text itself, you get confused quickly: three bytes become four characters, so a PNG's eight-byte signature occupies about eleven characters in encoded form, and their values are unrelated to 89 50 4E 47. Decode first, then look.

Signatures are evidence, not guarantees

None of this proves a file is well-formed. A signature check answers "which decoder should I hand this to", and a decoder's own validation answers the rest. That is the right division of labour: the signature is the cheap, reliable first question, and the format's own integrity rules — chunk lengths and a terminating IEND for PNG, the marker chain for JPEG — do the expensive work afterwards.

It also explains why "force this format" is a legitimate escape hatch for the rare file whose signature is wrong but whose contents are fine: real-world data is occasionally mislabelled at the source, and the bytes should be given the last word. Just be aware that you are overriding the only part of the input that was not a claim, so verify the result before shipping it.

Base64 Overhead: Why Data URIs Make Files 33% Bigger

zbinze — Tue, 10 Nov 2026 01:48:13 +0000

Base64 makes data bigger. Not slightly bigger — a third bigger, every time, with no exceptions and no settings to tune. The number is not a quirk of any particular implementation; it falls directly out of the encoding, and understanding where it comes from makes the inlining decision much easier.

Where the third comes from

Base64 exists to represent arbitrary bytes using only characters that survive text transport. The alphabet has 64 symbols, which is 6 bits of information per character. Bytes are 8 bits. So the encoder reads 3 bytes (24 bits) at a time and writes 4 characters (4 × 6 = 24 bits).

Three bytes in, four characters out:

3 bytes → 4 chars        4 / 3 = 1.333...

That is the whole story. A 300,000-byte image becomes a 400,000-character string. The overhead is exactly 33.3%, and it applies to the payload only — the data:image/png;base64, prefix adds a further 22 characters, which matters for tiny assets and is irrelevant for large ones.

The one escape hatch is padding. If the input length is not a multiple of three, the last group is padded with = characters that carry no information, so the exact size is 4 × ceil(n / 3):

1 byte → 4 characters, +300%
3 bytes → 4 characters, +33%
100 bytes → 136 characters, +36%
1,000 bytes → 1,336 characters, +33.6%
1,000,000 bytes → 1,333,336 characters, +33.3%

The small-input entries are the argument against inlining tiny assets for size reasons: a 1-byte file becomes 4 characters plus a 22-character prefix, and the prefix dominates.

Why gzip does not save you

On text, gzip routinely achieves 60–80% reduction, which is why the 33% figure is sometimes dismissed as irrelevant. That reasoning holds for JSON and HTML and fails completely for images.

Compression works by finding redundancy. JPEG, PNG, WebP and AVIF have already removed almost all of it — that is what those formats do — so their bytes are close to random from a compressor's point of view. Base64 encodes those incompressible bytes into a restricted 64-symbol alphabet, which adds no redundancy a compressor can exploit. The result is the worst of both worlds: the data is 33% larger and still does not compress.

You can measure this in one command:

# a real image, already compressed
base64 -w0 photo.jpg > photo.b64
ls -l photo.jpg photo.b64
gzip -9 -c photo.b64 | wc -c    # barely smaller than photo.b64

The garbled case is different. If you Base64-encode a text payload — JSON, XML, a log — gzip will compress the encoded form well, sometimes better than the original, because Base64 of text still contains recognisable structure. So "does gzip fix the 33%" has two answers, and they depend entirely on whether the payload was compressible to begin with.

The cost is not only bytes

Inflating a stylesheet or an HTML document has three costs that do not show up in a file-size comparison:

Render blocking. A data URI inside a <style> block or a linked CSS file is part of that file. The browser cannot paint until it has parsed it, and it cannot parse it until it has downloaded it. An external image request is not on that critical path.
No independent caching. Change one byte of a stylesheet that inlines twenty icons and every visitor re-downloads all twenty. As separate files they would each have their own cache entry and their own validator.
Parsing and memory. The bytes must be decoded and held as a string before they become an image. A 400 KB string in a stylesheet is 400 KB of text the parser must walk, and it stays in the CSSOM.

None of these are fatal. All of them are invisible if you only compare file sizes.

Two of those three costs come from how the string is embedded rather than from Base64 itself, which is worth separating: what a data URI actually is walks the grammar and the four ways one fails to render, and most of them are wrapping problems rather than encoding problems.

Where the break-even actually sits

There is no universal threshold, but the decision is narrow enough to state as rules of thumb:

Under ~2 KB, inline it. The bytes saved by avoiding a request (headers alone are often 300–800 bytes over HTTP/1.1, less over HTTP/2) can exceed the 33%. A single-colour icon or a tiny SVG is the classic case.
2–10 KB, it depends on caching. A favicon or a logo that never changes can be inlined safely; something that ships weekly should not be, and an asset used on ten pages should be a file so it is downloaded once.
Over ~10 KB, use a file. The overhead is now measured in kilobytes, there is no request to save, and you have given up caching for nothing.
Over ~1 MB, never inline it in a document. Beyond the size penalty you are now in territory where some tools truncate long attributes and some parsers get slow.

For images specifically, there is a better question than "how big is the Base64 string": could this be an SVG? A vector logo is a few hundred bytes of path data, encodes to under a kilobyte, and is resolution-independent. Inlining that is a clear win, and it is the case where the technique earns its reputation.

The table above covers round numbers. For a real file, convert an image and watch the payload grow — the page reports the exact character count, the byte count and the overhead that falls out of the two, in the Data URI, plain and CSS forms.

Measuring it on your own site

Two numbers tell you whether inlining is helping: the transfer size of the document that contains the data URI, and the transfer size of the equivalent page with external assets. If the inlined version is 30% larger, it is 30% larger — the 33% is not recoverable by the network layer.

The measurement is easy to get wrong in one specific way: comparing the uncompressed size of the image with the compressed size of the document. Compare like with like, and remember that the data URI's bytes travel inside a response that gzip can only partially shrink. Our PNG to Base64 and JPG to Base64 pages report the output length and the overhead as you convert, which is usually enough to see immediately that a 900 KB photograph should not be an inline background image.

For the cases where you do want the string — a small icon in critical CSS, an email template that cannot reference external files, a single-file HTML export, a JSON fixture in a test — the overhead is a fair price for self-containment, and knowing the exact number keeps it a deliberate choice rather than an accident. If you are deciding between the two ways of holding an image in memory rather than in a document, data URI vs blob URL covers the other half of this trade.

Decode a Base64 Image in Python, Node.js and the Browser

zbinze — Mon, 09 Nov 2026 02:05:32 +0000

Base64 is standardised, but decoders are not standardised in how forgiving they are. The same string that Python accepts can be silently mangled by Node, and the same string that Node happily decodes will make atob throw. Knowing which runtime does what turns a confusing failure into an expected one.

Python: strict, explicit, and the best choice for validation

Python's base64 module is the most honest of the three. By default it ignores newlines and other characters it does not recognise in the middle of the string; with validate=True it rejects anything outside the alphabet:

import base64, binascii

payload = uri.split(',', 1)[1] if ',' in uri else uri
payload = payload.replace('-', '+').replace('_', '/')       # base64url → standard
payload += '=' * (-len(payload) % 4)                        # restore dropped padding

try:
    raw = base64.b64decode(payload, validate=True)
except binascii.Error as e:
    raise SystemExit(f'not valid base64: {e}')

open('out.png', 'wb').write(raw)
print(len(raw), raw[:8].hex(' '))

Three things in that snippet are worth pointing out. The padding repair happens before validation, so a string that lost its = in transit is accepted. The alphabet conversion happens before padding repair, because the padding calculation uses the length after substitution — the two are the same length, so the order is safe, but doing it the other way round in a language with different assumptions is a common source of off-by-one bugs. And binascii.Error is the exception to catch; base64.b64decode does not raise ValueError.

If you want the strictest possible check, decode and then verify the result:

from PIL import Image
import io
img = Image.open(io.BytesIO(raw))
img.verify()          # raises on a truncated or structurally broken file
print(img.format, img.size)

verify() is the closest thing to answering "is this actually a complete image", which is a different question from "did the Base64 decode". A truncated JPEG decodes perfectly and fails here.

Node.js: lenient to the point of being dangerous

Buffer.from(s, 'base64') does not throw on invalid input. It discards characters it does not recognise and returns whatever it could decode, which means a truncated or polluted string produces bytes with no error at all:

const raw = Buffer.from(payload, 'base64');
console.log(raw.length, raw.subarray(0, 8).toString('hex'));

That is convenient for forgiving input and terrible for validation, because a string that lost the last 20% of its characters still returns a buffer. If you are decoding data you did not produce, validate the shape before decoding:

const clean = payload.replace(/[\r\n\t ]+/g, '');
if (clean.length % 4 === 1) throw new Error('truncated: length % 4 === 1');
if (/[^A-Za-z0-9+/=]/.test(clean)) throw new Error('illegal character in payload');
const raw = Buffer.from(clean, 'base64');

Node also handles base64url natively, which avoids the manual substitution entirely:

const raw = Buffer.from(token, 'base64url');   // '-' and '_' understood, padding optional

For files on disk, the whole thing is a one-liner:

import { writeFileSync } from 'node:fs';
writeFileSync('out.png', Buffer.from(payload, 'base64'));

The browser: `atob`, bytes, and one crucial detail

atob decodes to a "binary string" — one character per byte — which is not the same thing as bytes. Passing those characters anywhere that expects text corrupts everything above 0x7F:

const buf = atob(payload);
console.log(buf.length, buf.charCodeAt(0).toString(16));

const bytes = Uint8Array.from(buf, (c) => c.charCodeAt(0));   // real bytes
const blob = new Blob([bytes], { type: 'image/png' });
img.src = URL.createObjectURL(blob);

The Uint8Array.from step is not optional. new Blob([atob(payload)]) looks equivalent and produces a corrupt file for any image containing a byte above 127 — which is most of them, since compressed data is close to uniformly random. The symptom is an image that "almost" works: correct dimensions, green or grey bands, or a decoder rejecting it.

atob is also the strictest of the three about whitespace. Per the current specification it throws InvalidCharacterError on a newline, so a MIME-wrapped string must be stripped first:

const bytes = Uint8Array.from(atob(payload.replace(/[\r\n\t ]+/g, '')), (c) => c.charCodeAt(0));

Command line, for when there is no script

Two tools do this and they are not identical in strictness:

payload=$(printf '%s' "$B64" | sed 's/^.*,//')
printf '%s' "$payload" | base64 -d > out.bin        # GNU coreutils, stops on bad input
printf '%s' "$payload" | openssl base64 -d -A > out.bin   # -A ignores newlines

base64 -d on GNU systems reports invalid input and exits non-zero on a character outside the alphabet, which makes it a decent validator. macOS uses BSD base64 with -D instead of -d. Follow either with a signature check, which is the only way to know what you got:

file out.bin          # → PNG image data, 1 x 1, 8-bit/color RGBA, non-interlaced
xxd out.bin | head -1

A fifth way in the browser: let `fetch` do it

There is an approach that skips atob entirely and avoids every size limit discussed above, because the browser decodes the data URI internally:

const blob = await (await fetch(uri)).blob();     // uri is the full data: string
img.src = URL.createObjectURL(blob);
const bytes = new Uint8Array(await blob.arrayBuffer());   // if you need the bytes

fetch understands data: URLs as a scheme, so this works with no network request. It returns a Blob directly, which pairs naturally with a blob URL and with arrayBuffer() for byte inspection, and it does not build an intermediate binary string — so the double-memory problem of atob plus Uint8Array does not arise.

Two caveats. A strict Content-Security-Policy can block this: the fetch is governed by connect-src, so a policy that does not allow data: there will fail the request, and the error message talks about the connection rather than about Base64. And fetch is asynchronous, which is usually an improvement but does change the shape of surrounding code.

For a converter that decodes on every keystroke it is the simplest of the five approaches; for a script that needs to validate and repair the input first, doing the normalisation yourself and then calling one strict decoder remains clearer.

A behaviour comparison worth remembering

Same input, three runtimes, three outcomes:

Contains \n — Python: ignored by default · Node: ignored · browser atob: throws
Contains spaces — Python: ignored by default · Node: ignored · browser atob: throws
Contains %3D — Python: error with validate=True · Node: % skipped · browser atob: throws
Missing padding — Python: error · Node: decodes · browser atob: throws
Length % 4 == 1 — Python: error · Node: decodes (wrong bytes) · browser atob: throws
Contains - or _ — Python: error (urlsafe variant needed) · Node: 'base64url' handles it · browser atob: throws

The pattern is that Node never tells you anything and Python tells you if you ask. Neither is wrong for its intended use — Node optimises for tolerant ingestion of real-world data, Python for correctness by default. The practical advice follows directly: decode with the strictest runtime you have, and do the normalisation yourself. If you repair the input explicitly, record what you repaired, and verify the output bytes afterwards, the three runtimes agree — and you find out about a truncated string instead of rendering half an image.

That last step, verifying the decoded bytes, is the one people skip. Two checks cover most of it: the first bytes should match a known format signature (see image file signatures), and the length should match what the producer reported. If the length is short, the string was truncated in transit — the arithmetic behind that check is in line breaks and padding. If you would rather not write it, Base64 to Image performs the whole sequence — normalise, repair, decode, identify, verify — and reports each step it took, including the ones it decided not to take, which is often the more useful information.

The reverse direction has its own traps, and they are not symmetric. Encoding accepts bytes without complaint, so a wrong header or a missing prefix only surfaces later, at the consumer. Image to Base64 in JavaScript covers that side, including what each browser appends to the string without being asked.

Data URI vs Blob URL: Which Should You Use for Images?

zbinze — Sun, 08 Nov 2026 01:35:33 +0000

When you have image bytes in memory and want to display them, there are two ways to get them into an img element without a server round trip. They are frequently treated as interchangeable, and they are not: one is a portable but expensive text encoding, the other is a cheap reference that only exists while the page does.

The short version

Data URI — data:image/png;base64,iVBOR... — the bytes encoded as text, embedded in the URL itself. Self-contained, portable, serialisable, ~33% larger, and it lives in the DOM as a string.
Blob URL — blob:https://example.com/5f2a... — a reference to a Blob the browser holds in memory. No encoding, no size penalty, but it exists only in the document that created it.

// data URI: the bytes are in the string
img.src = 'data:image/png;base64,' + base64Payload;

// blob URL: the bytes stay in a Blob, the URL is just a handle
const url = URL.createObjectURL(blob);
img.src = url;
// later, when the image is gone:
URL.revokeObjectURL(url);

What each one costs

The data URI's 33% is structural, not an implementation detail: Base64 packs three bytes into four characters, and image bytes are already compressed, so gzip does not win them back. A 300 KB photograph becomes a 400 KB string, and inside JavaScript that string is stored as UTF-16 — two bytes per character — so it occupies about 800 KB in memory, on top of the original bytes you still hold.

The blob URL's cost is essentially zero. The browser keeps the bytes once, in the Blob you already created, and the URL is a short string that points at them. There is no encode step, no decode step, and no second copy.

That difference decides most cases on its own. If the payload is large or transient — a preview of a file the user just selected, a generated image, a decoded Base64 payload — a blob URL is the right answer.

What each one can do

The trade-off runs the other way for portability, and this is where the choice stops being about size.

A data URI is a value. You can put it in a JSON response, write it into an HTML file, store it in localStorage, paste it into an email, embed it in CSS, or send it to a colleague in a chat message. It survives serialisation, page reloads and process restarts, because everything needed is in the string.

A blob URL is a handle. It is scoped to the document that created it: open the same URL in a new tab and it means nothing; save it to a file and it is a dead reference; reload the page and every blob URL the previous document created becomes invalid. It also cannot be used across origins.

JSON.stringify({ src: 'blob:https://example.com/5f2a...' });  // serialises fine
// ...and means nothing to whoever reads it

The memory leak nobody notices

Blob URLs must be revoked. Every createObjectURL call pins a Blob in memory until either the page is destroyed or you call revokeObjectURL. In a preview that updates on every keystroke — exactly the pattern this site's decoder uses — forgetting to revoke means you accumulate one pinned image per paste:

let currentUrl = null;

function show(blob) {
  if (currentUrl) URL.revokeObjectURL(currentUrl);   // release the previous one
  currentUrl = URL.createObjectURL(blob);
  img.src = currentUrl;
}

Revoking a URL that an <img> has already loaded is safe and correct: the image keeps its decoded pixels, and the underlying bytes are released. Revoking while an image is still loading cancels the load in some browsers, so revoke the old URL when you replace it, not the new one you just assigned.

The same leak exists for data URIs, but in a less visible form: a long string held in a DOM attribute is memory that only goes away when the element does. A 400 KB string set as img.src and then replaced leaves the browser free to release it, but the string in your own variable does not go anywhere until you drop the reference.

Where each one wins in practice

Use a blob URL when:

previewing a file or a decoded payload, especially more than a few hundred kilobytes;
the image is generated (canvas, createImageBitmap, a decoded Base64 payload) and you control its lifetime;
you are downloading it — URL.createObjectURL plus the download attribute is the standard way to save bytes without a server;
the same bytes are shown more than once, since the URL is reusable and the data URI would be duplicated in each attribute.

Use a data URI when:

the value has to survive outside the current document — JSON, localStorage, an email template, an HTML file;
you are embedding a small asset in CSS or an HTML document where a second request would cost more than the bytes;
you are producing something a human will copy and paste, which is the entire premise of a Base64 converter.

Neither, when: you already have a real URL. An object or file served over HTTP is cached, streamable, and costs the browser nothing to display. Encoding bytes to Base64 to avoid a request is a trade that only pays off for small assets — see why Base64 makes your page 33% bigger for where that line falls.

There is one more case worth naming, because it is the one people reach for a data URI to solve: getting the string into a place that only accepts text — a JSON field, a config file, an email template. Neither a blob URL nor a data URI is the right answer there if the image is large; a real URL plus a text reference is. And if you are producing that string by hand rather than in code, Image to Base64 exists precisely to emit the right wrapper for the consumer you have in mind.

A note on decoding the other direction, since it comes up in the same code paths: if what you hold is a Base64 string rather than a Blob, you can go straight to a blob URL without touching atob — await (await fetch(dataUri)).blob() does the decoding internally and hands you something createObjectURL accepts. That is the shortest path from a pasted string to a rendered preview, and it is what this site's decoder does; Base64 to Image shows the result while also verifying that the bytes are what the header claimed.

Either way the starting point is the same: bytes you already hold. When those bytes come from a file the user picked, the conversion step itself — read the file, encode it, attach a header that matches the real format — is in Image to Base64 in JavaScript.

The one security note worth carrying

Neither scheme executes scripts on its own: an <img> element does not run scripts inside an SVG, whether the source is a data URI or a blob URL. The risk appears when the resource stops being an image — navigating a top-level document to an image/svg+xml data URI, or passing user-supplied bytes to something that treats them as markup. Keep the rule narrow and concrete: images go in img, and a blob: URL is how you hand the browser bytes you already trust in memory.

One CSP detail catches people out in both directions. Data URIs need img-src data: to be allowed, and blob URLs need img-src blob:. A page with img-src 'self' blocks both — silently, with only a console violation to explain it. If you add either technique to a site with a strict CSP, add the matching source expression at the same time, or you will spend an afternoon debugging Base64 that was never broken.

Questions people actually ask

When should I use a data URI instead of a blob URL? When the value has to survive outside the current document — a JSON response, localStorage, an HTML file, an email template, or something a person will copy and paste. A data URI is a value that serialises; a blob URL is a handle that only means something inside the document that created it.

Why does a blob: link stop working after a reload? Because it is scoped to the document. Reload the page and every blob URL the previous document created becomes invalid; open the same URL in a new tab and it refers to nothing; save it to a file and it is a dead reference. It cannot cross origins either. The bytes only ever existed in that document's memory.

What does each one cost? A data URI is about 33% larger, and that is structural — Base64 packs three bytes into four characters, and image bytes are already compressed, so gzip does not win it back. Inside JavaScript the string is stored as UTF-16, so a 300 KB photograph becomes a 400 KB string occupying roughly 800 KB of memory. A blob URL costs essentially nothing: the bytes stay in one Blob and the URL is a short handle.

Do I have to revoke blob URLs? Yes. Every createObjectURL call pins a Blob in memory until the page is destroyed or you call revokeObjectURL. In a preview that updates on every keystroke, forgetting this accumulates one pinned image per paste. Revoke the previous URL when you assign a new one — revoking a URL an image has already loaded is safe, but revoking while it is still loading cancels the load in some browsers.

Which should I use to preview a large file the user just selected? A blob URL. Large or transient payloads are exactly the case where the 33% overhead and the doubled memory of a string in the DOM are pure loss, and you control the lifetime, so the revoke discipline is easy to get right.

Base64 Line Breaks and Padding: Why They Break Decoders

zbinze — Sat, 07 Nov 2026 01:42:07 +0000

Two formatting rules cause more Base64 failures than every other cause combined. Both are part of the standard, both are routinely violated in the wild, and strict decoders reject the results — which means the same string can work in one language and fail in another.

The first rule is that Base64 output is often wrapped across lines. The second is that the tail is padded with = to round the length up to a multiple of four. Neither changes the data. Both change the string, and decoders disagree about how forgiving to be.

Why 76 characters

Base64 predates JSON, HTTP/2 and email attachments. It was designed to survive transport through systems that cared about line length, and the dominant one was email: RFC 2045 wraps encoded bodies at 76 characters, a limit chosen to stay under SMTP's 998-octet line maximum while keeping quoted-printable output readable. Every four Base64 characters represent exactly three bytes, so 76 characters is 57 bytes per line — an awkward-looking number that is really just "72 characters plus a little headroom".

That is why you see this shape in PEM files, MIME bodies and log output:

iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAF
AAH/q842iQAAAABJRU5ErkJggg==

The newline is not data. It is transport furniture that leaked into the copy-paste layer, and a decoder that treats the string as opaque bytes will stop at the first \n and report an illegal character at position 76.

Why the padding exists, and why the remainder matters

Each group of four Base64 characters encodes three bytes. When the input length is not a multiple of three, the encoder pads the output with =:

1 leftover byte → 2 characters + ==
2 leftover bytes → 3 characters + =
0 leftover bytes → no padding

So the encoded length is always a multiple of four, once padding is included. Turn that around and you get the single most useful diagnostic rule in this whole area:

After normalisation, a complete Base64 string's length modulo 4 is 0, 2 or 3. A remainder of 1 is impossible.

A remainder of 1 does not mean "slightly malformed". It means characters are missing. There is no 1-byte remainder case in the encoding, so some input byte pair has been cut in half. In practice the cause is almost always truncation: a log line capped at 1024 characters, a terminal that wrapped and lost a line during selection, a database column with a VARCHAR(n) limit, or a copy that stopped a character early.

This is worth stating plainly because it is the difference between a fixable problem and an unfixable one. A decoder can repair missing padding — adding = is deterministic and lossless. It cannot repair a missing character; anything it produces will be a corrupted image, and a tool that "helpfully" pads and decodes a remainder-of-1 string is handing you a picture that is wrong in a way you cannot see.

What different decoders do about it

The behaviour you get depends entirely on which implementation you use, and the differences are not documented prominently anywhere.

Python is strict and explicit. base64.b64decode(s) ignores newlines but rejects other junk; adding validate=True makes it reject any character outside the alphabet:

import base64
raw = base64.b64decode(payload, validate=True)   # binascii.Error on bad input

Node is the opposite extreme. Buffer.from(s, 'base64') silently discards characters it does not recognise. It will decode a string containing spaces, quotes and stray prose without complaint:

Buffer.from('iVBO\nRw0K Ggo=', 'base64').length   // 10 — no error, junk skipped

That leniency is convenient when you know the input is nearly right, and dangerous when you do not: a truncated string still returns bytes, just fewer of them, and nothing tells you the difference.

Browsers sit in the middle. atob throws InvalidCharacterError on a newline — but only in strict spec-compliant form; historically it ignored whitespace. Normalising first removes the ambiguity:

const clean = payload.replace(/[\r\n\t ]+/g, '');
const bytes = Uint8Array.from(atob(clean), (c) => c.charCodeAt(0));

A normalisation order that does not lose information

The order matters, because some repairs change what the next check sees. This sequence is what our Base64 to Image tool applies, in this order, reporting each step it took:

Strip the data: prefix if present — everything up to the first comma. If there is no comma, there is no prefix.
Decode percent-encoding (%3D → =). This happens before the alphabet check, otherwise % looks like an illegal character.
Remove whitespace and line breaks.
Strip surrounding quotes, which appear when a string is copied out of JavaScript, JSON or a shell script.
Unescape literal \n and \t sequences, which appear when the encoded string was itself stored inside a JSON string.
Convert the URL-safe alphabet (- → +, _ → /) if those characters are present.
Fix padding — add the = characters the length says are missing, or remove surplus ones.
Check the remainder. If it is 1, stop and tell the user the data is truncated. Do not decode.

Steps 7 and 8 are the pair that separates a useful decoder from a plausible one. Without step 8 you ship a corrupted image silently; without step 7 you reject every string that lost its padding in transit, which is a large fraction of them.

Step 1 assumes there is a header to strip. In logs, database columns and message queues the string usually arrives bare, with no data: at all — nothing to strip, and it is worth decoding the raw string without the prefix rather than pasting it into a converter that insists on one.

Deciding when to accept a repaired string

Repair is not the same as validation. Adding padding is safe because it is reversible and determined by the data itself. Stripping whitespace is safe for the same reason. But once you have repaired the form, the only real check on the content is structural: does the decoded byte stream look like the thing it is supposed to be?

That is why the tool reports what it changed rather than quietly fixing things. "Removed whitespace and line breaks (57 positions)" is information: it tells you the string went through a MIME-aware channel. "Added 2 padding characters" tells you the source dropped them — often a URL, a query parameter, or a JavaScript string that was trimmed. Both are normal, and both are worth knowing about when the image that comes out is not the image you expected.

The one repair that should never be silent is removing characters from the middle of the data. If a decoder has to throw away something other than whitespace to make a string valid, the honest answer is that the input is not Base64 — see what a data URI actually allows for the header half of this problem, and Base64 image not showing for the full troubleshooting order when you have already decoded something and it still will not display.

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.