← Blog · Troubleshooting · 4 min read
Why Your QR Code Won’t Scan — and How to Fix It
A QR code that fails in the wild almost always fails for one of six physical reasons — and every one of them is checkable before you print. Work down the list in order; the early items account for most failures.
1. The contrast is too low
Readers hunt for dark modules on a light field. Pastel-on-cream passes on a bright monitor and dies on paper under warm light. The working floor is a contrast ratio of about 4:1 — the same threshold this site’s generator enforces on its theme palettes. If your colours are close, darken the modules rather than lightening the background; paper is never as white as a screen.
2. The quiet zone got cropped
The white margin is not padding — it is how the reader finds where the symbol begins, and the specification wants at least four modules of it on every side. Designers crop it because it looks like wasted space; the code then looks perfect and reads on almost nothing. This is the most common failure because it is invisible.
3. It is printed too small for the distance
The rule of thumb is one tenth of the reading distance: a code scanned from 30 cm needs about 3 cm of printed code. Small codes fail slowly — newer phones cope, older ones hunt and give up — which is why undersized codes pass a desk test and fail in service. The full arithmetic, with worked examples, is in the print-size guide.
4. The colours are inverted
A light code on a dark background reads as a striking design choice and an unreadable symbol. Most phone readers simply refuse inverted codes rather than attempting both polarities.
5. Too much data, too little correction
The more characters you encode, the denser the grid; the denser the grid, the smaller each module at the same print size. A 300-character URL with a logo punched in the middle at low error correction is asking the decoder to reconstruct a lot from a little. Shorten the URL, raise the error-correction level, or drop the logo — error correction can only absorb so much.
6. Decorative modules meet an old reader
Dots, diamonds and rounded shapes scan fine on current phones, but stricter or older decoders want plain squares. If your styled code fails somewhere important, regenerate with standard modules — the data is identical, only the drawing changes. You can verify any of this in seconds: scan your own file with the scanner linked below before anything goes to a printer.
Static code — nothing expires, no account, no sign-up.
Test a code in the scanner →