← Blog · Troubleshooting · 3 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 stops reading reliably. It is easy to miss 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 can look like a striking design choice. Not every reader tries both polarities, so some refuse an inverted code outright.
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, drop the logo, or raise the error-correction level — error correction can only absorb so much. The single generator always uses H, the highest level; the bulk generator lets you choose, so raise it there. Text in other scripts, and emoji, take more room than their length suggests; the measurements are here.
6. Decorative modules meet a strict reader
Square and rounded modules are the safest choice. Dots, and decorative shapes such as diamonds, hearts and stars, are not read reliably by every decoder, so test them before printing. If your styled code fails somewhere important, regenerate with square 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.
Scan your file before it goes to the printer. The image never leaves your device.
Test a code in the scanner →