Why won’t my QR code scan? Five causes, and which of them we can measure

Start by ruling out the quiet zone

A QR symbol is more than the black squares. The specification defines a margin of four modules of clear space on all four sides, and a decoder treats that margin as part of the symbol — it is how the decoder finds the edges at all. Crop it, print artwork against it, or place the code flush into a coloured panel, and a code that is otherwise perfect stops resolving.

This is the first thing to check because it is the cheapest to fix and the easiest to do by accident. Design tools export a QR as a tight bounding box surprisingly often, and a layout that then butts it against a rule or a photograph has removed something the standard requires.

Four modules means four modules of the code’s own grid, not four millimetres and not a fixed percentage. On a version 2 symbol that is 12% of the printed width per side; on a version 10 symbol it is 6%. If you are working to a percentage, you are working to the wrong number on every version but one.

The quiet zone is the only part of a QR code you can delete without it looking deleted.

Then count the modules, because the payload decides them

A QR symbol’s size is its version, and a version is a fixed grid: version 1 is 21 modules across, and each version after it adds four. Version 2 is 25, version 3 is 29, version 10 is 57. The version is chosen by how much data you are encoding and at which error correction level — not by how large you want the code to be.

That has a consequence people find counter-intuitive: two codes printed at the same width can have very different module sizes, and the one carrying the longer link is the one that fails. A 22-character short link and a 90-character tracked URL printed side by side at 25mm do not have the same chance of scanning, because the second one is drawing a denser grid in the same square.

This is the whole argument for a short link on anything printed. It is also arithmetic rather than opinion: divide the printed width by the module count, quiet zone included, and you have the size of one module. The print size calculator on this site does exactly that and shows its working.

Every figure here is division. The version-to-module rule is 4v + 17 from ISO/IEC 18004, the quiet zone adds eight, and the last column is 25 divided by the third. What none of these columns says is which of them still scans — see the last section.

Contrast has a formula, so use it instead of your eyes

A pale grey code on white looks fine on a screen at 200% and fails on a table tent. The reason is that a decoder has to separate dark modules from light ones under whatever light the room has, and “dark enough” is a ratio rather than an impression.

The ratio is computable. Relative luminance and the contrast formula that WCAG uses for text apply to a QR code’s two tones exactly as they apply to type, and you can run them on any two colours before anything is printed. Black on white is about 18:1. The pale grey that design teams reach for when a code is “too heavy” is often under 2:1, and it is the single most common cause of a code that scanned in the studio and not in the restaurant.

Inverted codes — light modules on a dark background — are a separate problem and a real one. Some decoders handle inversion and some do not, and the ones that do often try it only after failing the normal orientation, which costs time a person standing at a counter does not give you.

If you are asking whether a code is too pale, you are asking a question with a number for an answer.

Logos and artwork spend error correction you may need

A logo in the middle of a QR code works because the format carries redundancy: at error correction level M, roughly 15% of the symbol can be damaged and still decode. Covering the centre with a mark spends that budget, and so does a scuff, a fold, a coffee ring or a print defect.

The trouble is that a code with a logo usually still scans on the phone of the person who made it, held six inches away in good light on a clean screen. The redundancy is not gone, it is spent — and what it was for was the wear the code meets afterwards.

The honest framing is that error correction is a budget with two claimants, and the designer sees only one of them. If you want a logo, raise the level to Q or H before you place it rather than after, and accept that the code gets physically larger for the same data.

And the size in millimetres, which we are not going to give you

Everything above is a specification or a division. The question you actually came with — how small can I print this — is neither. It depends on the camera, the lens, the lighting, the substrate, the ink, the distance and the patience of the person scanning, and the only way to answer it is to print a stratified corpus and scan it with real phones until the failures form a boundary.

That study has not run here. We have designed it — 400 samples, six sizes, six devices, matte and glossy stock — and until it has been run and published, this site does not show a minimum print size, does not show a scanability score, and does not band a code as safe or unsafe. Where those numbers would go, the page says it is not calibrated and why.

You will find millimetre figures elsewhere, and some of them are probably fine. What you will rarely find is the corpus they were fitted to. A rule of thumb worth having in the meantime is distance divided by ten — a code roughly a tenth of the distance it will be scanned from — which our calculator shows, labelled as a rule of thumb, alongside everything about the symbol that is actually derived.