Why a code will not scan

Before measuring anything, establish which half of the system is broken.

1. Does the code scan from the screen, in the design file, on any device? If it does, the encoding is sound and your problem lives in production or in the reader. If it does not, the file itself is wrong and no amount of reprinting will help.
2. Does it scan but do nothing useful? A code that decodes and then opens an error page, or opens nothing, is not a scanning failure at all. The pattern did its job. Skip everything below and go and look at the destination.

The most common physical cause, and the least visible one, because a code that is too small looks completely normal. Measure the printed width, count the modules along one edge, and divide. Below about half a millimeter per module you are outside what ordinary phone cameras do reliably.

Two symptoms point here specifically. The code reads when you move the phone closer than feels natural, and it reads for some people and not others, because handsets differ in camera resolution and in how close they can focus.

A QR code needs four modules of clear space on every side; a linear barcode needs a wider margin still at its ends. This is the failure that gets introduced after the code was approved, in layout, by someone tightening a design.

• A border or keyline drawn tight around the code.
• The code sitting on a colored panel whose edge falls inside the margin.
• Text or an image crowding one side.
• A trim or fold passing through the margin.
• The code placed in a container with the background showing through, so the margin is whatever happens to be behind it.

The tell is directional failure: the code reads when you approach from one angle and not another, or reads when you cover part of the surrounding artwork with a finger. That is worth trying, because it turns a guess into a demonstration.

Photocopy the proof in black and white, or desaturate the file. If the pattern is muddy in grayscale, the decoder cannot separate the modules either, whatever the colors look like to you.

For a linear barcode failing at a checkout while scanning fine on a phone, suspect the ink color before anything else. Red and orange bars are invisible to the red-light lasers that point-of-sale scanners use, and nothing about that failure is visible in the studio.

A code can be geometrically perfect and still unreadable because of what the light is doing.

• Gloss and lamination throw a specular highlight that erases part of the symbol, and it moves as the reader moves, so failures feel random.
• Dim light pushes the camera to higher gain and longer exposure, adding noise and blur. A code that works at lunchtime can fail in the same room at night.
• A screen showing the code at low brightness loses contrast. Turn it up before blaming the code.
• A very close phone may fail to focus. Some handsets have a minimum focus distance well above where people instinctively hold a small code.

A QR decoder reconstructs a square grid from fixed reference points, and it can only correct so much.

• Stretching. If the code was scaled without locking the aspect ratio it is no longer square, and it will not read at all. Measure both sides.
• Curvature. Wrapped around a bottle or a pipe, the modules near the edges compress. Keep codes to a shallow arc.
• Folds and creases. A crease is a break in the grid rather than a smudge.
• Damage over a finder pattern. Error correction protects the data region; it does not protect the three corner squares. A code with a scuffed corner square is not degraded, it is unfindable.

If the pattern decodes for you and fails for a particular person, the difference is usually their device or their software.

• Older handsets may not scan from the camera app at all and need a separate scanner.
• Inverted codes, light modules on a dark background, are not universally supported.
• A code opened inside an app's built-in browser can behave differently from the same link in the real browser, particularly for anything that triggers a download or hands off to another app.
• Some scanner apps show the decoded text and wait, rather than acting on it. That is a feature, and it looks like a failure to somebody expecting a page to open.