Why your QR code is not scanning

The code prints beautifully, everybody at the agency scans it on their iPhone, and then it dies on the actual menu card in a dim restaurant. Failures like this almost always have one specific, findable cause — and there are only eleven of them, each with its own section below.

The sixty-second diagnostic

Work down this list in order. It resolves most cases before you get to the bottom.

1. Scan the file on your screen. If the digital original does not scan at 200% zoom, the problem is the code itself, not the printing.
2. Read the decoded text. Use any scanner that shows the URL before opening it. If the text is wrong, nothing downstream matters.
3. Open that URL in a browser by hand. A 404 is a website problem wearing a QR code costume.
4. Measure the printed symbol. Compare it against the distance it is read from — roughly one tenth of that distance.
5. Check the margin. Four modules of blank space on all four sides.
6. Check the contrast in greyscale. Convert the artwork to greyscale; if the pattern goes muddy, so does the decoder’s view of it.
7. Try a second phone, ideally a cheap Android one, in the light the code actually lives in.

Contrast and the inversion trap

A decoder does not see colours. It converts the image to greyscale, picks a threshold and calls everything below it a dark module, so what matters is luminance difference, not how different the two colours look to you — which is how a confident brand orange on white ends up as a blank square. Inversion, light modules on a dark background, is the other half of it: plenty of readers cope, the specification’s model does not, and a meaningful minority of camera apps simply refuse.

The ratios that pass, the ones that fail and a rated table of twenty combinations are in the guide to QR code colours and contrast. If you only do one thing here, convert the artwork to greyscale and look at it.

The quiet zone

Four modules of blank margin on every side is part of the symbol, not decoration around it. The decoder uses that boundary to find where the code ends. Codes pushed flush against a coloured panel, bled to the trim edge of a page, or dropped onto a photo lose it, and readers never lock on. If space is tight, shrink the code and keep the margin — that trade always wins.

Size, distance and blur

One tenth of the reading distance, and no module under about 0.4 mm in offset or 0.6 mm on thermal stock: measure the printed symbol against both. The print size guide has the distance table, the per-process floors and the arithmetic from module count to millimetres.

Blur is the same failure arriving by a different route, and it is the half that is specific to troubleshooting. Phone cameras cannot focus below roughly 8–10 cm, so a very small code pushes the user back to a distance where it is only a few dozen pixels across. Motion blur does the rest: a code on a bus, a delivery van or a screen in a lift is being read by a moving camera. Both are fixed by making the code larger, not by adding error correction.

Glossy stock, lamination and screens

A gloss varnish or laminate reflects a hard highlight straight back into the lens and blows out part of the symbol — matte stock is worth more than any software setting, and the print size guide covers the finishes and substrates in full. The version people forget is the screen: a phone showing a boarding pass at minimum brightness, behind a glass counter, under a strip light, is a reflective grey square. Turn the brightness up, tilt the screen away from the light source, and stop it auto-dimming before you hold it under a scanner.

A damaged or over-logoed centre

Error correction tolerates missing data, but not missing structure. The three big squares in the corners are the finder patterns; the dotted line running between them is the timing pattern, which tells the decoder the module grid. If a logo, a fold, a staple or a die-cut touches any of those, the code is not degraded, it is dead. Logos belong in the centre, small, with a white ring around them — see putting a logo in a QR code without breaking it.

The wrong error correction level

Both directions are a real failure mode. Too low, and a scuff on a warehouse label takes the code out. Too high, and the extra redundancy pushes the symbol to a higher version — more modules — which shrinks every module at your fixed print size. Choosing H “to be safe” on a 2 cm code makes it less readable. What L, M, Q and H really cost you works through the trade with numbers.

Version creep from a long URL

Every extra character can push the symbol up a version and add four modules per side. A 40-character link at level M is a 29-module version 3; the same link with four UTM parameters bolted on runs to about 120 characters, which is a 45-module version 7. Printed at the same 25 mm, the modules shrink from 0.86 mm to 0.56 mm and the code stops being readable at arm’s length.

Shorten the destination — a clean path on your own domain rather than a long query string — before you raise error correction or enlarge the artwork.

Folds, curves and cylinders

Never print a code across a fold, a spine, a perforation or a seam. The fold line reads as a break in the modules and the crease throws a shadow. Curved surfaces — cans, bottles, tubes, cups — distort the grid; put the code on the flattest part of the surface, keep it small relative to the diameter, and this is one of the few cases where raising error correction genuinely helps. For very tight label space, a different symbology may be the better answer: Data Matrix packs the same short payload into a smaller footprint and tolerates direct part marking.

The short link died

A QR code encodes text literally and never changes. If that text is a bit.ly or goo.gl address, the code’s lifespan is the lifespan of somebody else’s service. Google retired its own shortener and those links stopped resolving; every printed code pointing at one became a dead square of ink. This is the single most expensive failure on the page because it happens years after the print run, at scale, and is unfixable.

Codes made with the generator here contain your URL literally — nothing on this site has to keep running for them to work. If you want editability, point the code at a redirect on a domain you own; the reasoning is in static versus dynamic QR codes.

Camera app quirks

• iOS: the Camera app has scanned codes for years, but it can be switched off in Settings → Camera → Scan QR Codes. If a colleague’s iPhone “cannot scan”, check that first.
• Android: behaviour varies wildly by manufacturer. Some stock camera apps scan automatically, some need a mode toggle, some do nothing and the user has to open Google Lens. Never design for the best-case reader.
• Both: some payload types — WiFi credentials, vCard contacts, calendar events — are handled inconsistently. A plain https:// URL is the format with the fewest surprises.

It scans, but the page 404s

At this point the QR code has done its job. Check for http:// where the site forces https://, a staging or preview hostname, a page renamed after the artwork went to print, a URL that requires a login, a trailing slash the server cares about, or a link that only resolves inside your office network. Decode the code, paste the text into a browser, and the real error appears immediately.

Before any print run, generate the final artwork, print one copy at final size on the final stock, and scan it with the worst phone in the office, at an angle, in the light the code will live in. That one test catches most of this page.