A QR code that refuses to scan almost always has one of the three root causes below. Work through the list top-to-bottom.
1. Contrast too low
The most frequent cause. QR scanners need a clear black-white edge profile. Checks:
- Foreground vs. background contrast: at least 4.5 : 1 (WCAG AA). If unsure, use
https://webaim.org/resources/contrastchecker/. - Inverted colours: light codes on dark backgrounds only work with scanner apps that explicitly support inversion — the built-in phone camera usually does not. Dark foreground, light background is the safe default.
- Logo too large: if you embedded a logo, reduce it to at most 25 % of the code area.
2. Size too small
Rule of thumb for print: QR side length ≥ scan distance ÷ 10.
| Scanning from | Minimum side length |
|---|---|
| 30 cm (desk) | 30 mm |
| 1 m (poster, shelf) | 100 mm |
| 3 m (shop window) | 300 mm |
| 10 m (trade-show banner) | 1 000 mm (100 cm) |
The browser scales automatically; for print always use vector format (SVG or PDF), do not upscale PNG — it blurs the edges.
3. Too much data
Very long URLs, long text, large vCards produce a denser QR matrix (higher QR version) with smaller modules. Small modules = hard to scan, especially in low light or under motion blur.
Countermeasures:
- Long URLs → promote to dynamic (the redirect link is shorter, the matrix is less dense)
- vCards → trim to essential fields
- File QR codes → prefer a landing-page URL that links to the download, instead of the download URL directly
4. Edge cases (rarer)
- Strongly curved surface (mugs, bottles): unreliable below 60 mm diameter
- Reflections: glossy lamination bounces the phone LED, matte finish is safer
- Folds across the code: any crease through the matrix kills scan rate
If nothing works
In the dashboard, open the code, download the PNG and view it in the browser, then scan from a phone. If it scans there, the problem is the print/medium, not the code.