Troubleshooting
QR code not scanning: the checklist
Work through these in order, because they are ranked by how often they are the actual cause: quiet zone, contrast, size for distance, glare, blur from upscaling, inverted colours, and finally the destination. Most failures are found in the first three.
1. Quiet zone (most common)
The blank margin must be four modules on every side. Not four millimetres — four modules, which scales with the code. A designer's fixed 2 mm padding on a code with 0.8 mm modules is less than three modules and the code often will not be found at all, which is a failure before any error correction can help.
Check: is there text, a border, a coloured panel or a photograph inside the margin?
2. Contrast
Decoders threshold on luminance, not hue. Two colours that look different can have almost the same luminance. Aim for at least a 40% luminance difference; below 30% it will fail on most cameras.
Also check the code is dark on light. Inverted codes work on some scanners and not others, for no design benefit.
Our validator computes the actual luminance contrast and decodes the rendered output.
3. Size for the distance
Printed width must be at least scanning distance ÷ 10.
| Distance | Minimum width |
|---|---|
| 30 cm (a table) | 3 cm |
| 1 m (a poster in a corridor) | 10 cm |
| 3 m (across a lobby) | 30 cm |
| 10 m (a large sign) | 1 m |
If the code is too small for the space, the fix is usually a shorter payload, not a bigger code — fewer characters means a lower version and larger modules at the same width.
4. Glare
Gloss lamination, spot UV, foil, glossy screens and laminated table tents all produce specular reflection. The decoder sees a uniform bright patch, not damaged modules, so error correction does not help at all.
Fix: matt finish, and mount the code vertically rather than flat.
5. Blur from upscaling
A small PNG scaled up in a layout tool interpolates every module edge into a gradient. Always place SVG or PDF. If you must use raster, generate at final size × 300 dpi and never enlarge.
6. Print quality
- Ink spread on uncoated stock closes the gaps between modules — keep modules at 0.4 mm or larger.
- Thermal printers below 4 dots per module produce rounding errors — see labels.
- A code across a fold, a crease or a trim edge is broken in two ways at once.
7. The code itself is wrong
- A logo covering more than about 20–25% of the area, or covering a finder pattern.
- Module styling so organic that adjacent modules merge, damaging the timing pattern.
- The code was redrawn or traced by hand in a design tool.
- The image was saved as a lossy JPEG, which adds ringing artefacts at every edge.
8. The destination
If the code decodes but nothing useful happens: the URL is dead, the shortener has been retired, a corporate DNS filter blocks it, or a captive portal is intercepting it.
Test by decoding the code with our scanner and reading the string it produces — that separates a scanning problem from a destination problem in one step.
FAQ
What is the most common reason a QR code does not scan?
An inadequate quiet zone. The four-module blank margin is required for the scanner to find the code at all, and it is the first thing designers crowd.
Why does my QR code scan on screen but not in print?
Usually ink spread closing the gaps between modules, upscaling a raster image, or gloss finish causing glare. All three are invisible on screen.
Does raising the error-correction level fix a code that will not scan?
Rarely. Higher error correction increases the version, making every module smaller at the same printed size — which often makes scanning harder, not easier. Fix contrast, size and quiet zone first.
How do I tell whether the problem is the code or the destination?
Decode the code and read the resulting string. If the string is correct, the code is fine and the problem is the URL, the network or the destination page.