Troubleshooting
Why a QR code won't scan
Failures cluster into six causes, and they are not equally likely. This guide puts them in diagnostic order so you test the cheap explanations first and stop guessing at the expensive ones.
Updated
A code that will not scan has a small number of possible causes, and they are very unevenly distributed. Most people start by regenerating the code, which is almost never the problem. Working through the list below in order will resolve the great majority of failures in the first two steps.
1. The quiet zone
Check this first because it is the most common cause and the cheapest to rule out. The format requires four modules of blank space on every side, and a decoder uses that margin to find the boundary of the grid.
The margin disappears in predictable ways. A code is dropped onto a coloured background panel with no white box behind it. It is placed near a trim edge and the bleed eats the margin. Body copy is pushed up against it to save space in a tight layout. A sticker is applied overlapping a printed border.
Test by covering everything around the code with a plain sheet of white paper, leaving a generous margin, and scanning again. If it works, the margin was the problem, and no amount of regenerating will have helped.
2. Physical size relative to the payload
The second most common cause, and the one most often misdiagnosed as a camera problem. Scanning needs about ten times the code’s width in distance at most — but the real constraint is module width, and a long payload packs more modules into the same square.
Two codes printed at identical size can behave completely differently if one carries a 30-character link and the other a 300-character contact record. A sizing pass that accounts for payload length fixes this properly. The quick diagnostic is to generate the same content at double the size and scan that; if it works, you have a resolution problem, not a data problem.
Shortening the payload is usually the better fix than enlarging the print, because it costs nothing in layout. Strip tracking parameters from links. Cut optional fields from contact cards. Encode a link to a file rather than the file contents.
3. Contrast and reflection
The decoder has to threshold every module into dark or light. Three things sabotage that.
Insufficient contrast — a mid-grey code on a cream background, or a tinted code where the dark modules are not much darker than the light ones. Phone cameras apply their own exposure and white balance on top, and what looks distinguishable on a calibrated monitor often is not through a camera.
Specular reflection — gloss lamination or a varnished surface catching a ceiling light throws a highlight across part of the grid, and the decoder reads that whole region as light. Tilt the code, or the phone, and try again. If tilting fixes it, specify matte finish.
Inversion — light modules on a dark background. Modern phones usually manage it; older scanner apps and most dedicated hardware readers do not.
4. Print quality on the actual material
Ink spreads on absorbent stock. Dark modules thicken, light gaps narrow, and past a certain point the decoder cannot separate adjacent modules at all. This is why a code that proofs perfectly on coated card fails on newsprint at the same size.
Look at the printed code under magnification. If module edges are furry rather than sharp, or if the light gaps between dark modules have partly closed, the problem is the substrate and the answer is a larger code — twenty to thirty percent larger on absorbent material is a reasonable starting adjustment.
Curved surfaces cause a different distortion: one axis compresses, and the decoder’s alignment patterns can only correct so much. Keeping a code under roughly a third of a bottle’s circumference keeps it inside what the format handles.
5. Damage, overlays and logos
A logo dropped into the middle of a code works because error correction repairs the modules it destroys — until it does not. A centred overlay is the worst damage shape, concentrating loss into a few blocks rather than spreading it.
If a logo was added after the code was generated, remove it and scan the clean version. If the clean version works, the overlay is over budget: shrink it, raise the error correction level, or both.
Nothing repairs damage to the three corner finder patterns or the timing lines running between them. Those are what the decoder uses to locate the grid before error correction is even considered. A scuffed or covered corner is fatal.
6. The payload, not the pattern
If the pattern decodes cleanly and something still goes wrong, the problem has moved downstream. Decode the code with a reader app that shows the raw string and inspect it.
Common findings: a URL missing its scheme, so the string is treated as plain text rather than a link. A Wi-Fi payload whose password contains a semicolon or backslash that was not escaped, truncating the credential. A phone number with formatting characters the dialler rejects. A destination that has since moved, expired or gone HTTPS-only.
This class of failure is invisible from the image. The code is perfect; what it says is wrong.
7. The scanning app
Last, because it is rarely the answer but occasionally is. Some Android builds decode through the camera app, others require Lens. Some corporate device policies disable camera-initiated links entirely. Battery saver modes reduce camera frame rate and autofocus aggressiveness enough to matter on a marginal code.
If one device fails and three others succeed on the same printed code, you have found a device problem rather than a code problem — but treat it as a signal that the code is closer to the margin than it should be. A comfortably sized, short-payload code with a clean quiet zone scans on everything.