Why won't my QR code scan?

1. Low contrast between the modules and background

A scanner does not see color — it sees light and dark. It thresholds the image into two values, so what matters is the luminance difference between your dark modules and the background, not how different the hues look to a human eye. Two colors can look obviously distinct (red on green, navy on brown) yet sit at nearly the same brightness, and the camera collapses them into one gray blob.

The fix: aim for a contrast ratio of at least 3:1 between the modules and background, and 4.5:1 or better for reliable scanning across cheap cameras and bad lighting. Keep the data modules clearly darker than the background. If you want to tint a code, lean on near-black foregrounds and near-white backgrounds and verify the ratio — the full reasoning is in contrast for machine vision.

2. Inverted colors (light modules on a dark background)

QR codes are defined as dark modules on a light background. That polarity is part of the standard, and many real-world scanners — especially older or hardware-based ones — will refuse an inverted code outright, even when the contrast is perfect. Some modern phone cameras handle inversion, but you cannot count on it, and “works on my phone” is not the same as “works on every customer’s phone.”

The fix: keep the data dark and the background light. If your design demands a dark surface, put the QR code inside a light-colored panel rather than inverting the code itself. When in doubt, the safest combination is still black modules on white.

3. A logo or overlay too large for the error-correction level

QR codes carry redundant data so they still decode when part of the symbol is obscured. The error-correction level sets how much you can lose: roughly L 7%, M 15%, Q 25%, and H 30% of the code can be damaged or covered and still recover. A center logo eats into that budget. Drop a big logo onto a level-M code and you blow past the 15% it can spare, and the decode fails.

The fix: use error-correction level H whenever you place a center logo, and keep the logo well under the recovery budget — a practical safe maximum is about 25% of the code area even at level H, because some of that headroom must stay free for ordinary print noise and glare. See QR error correction explained for how the recovery actually works and why bigger is not free.

4. Not enough quiet zone around the code

The blank margin around a QR code is not decoration — it is the quiet zone, and the standard calls for 4 modules of clear space on all four sides. The scanner uses that border to tell where the code stops and the rest of the world begins. Crop it tight, butt text or a graphic right up against the edge, or place the code in a busy frame, and the locator can fail to register the symbol at all.

The fix: leave at least 4 modules of empty, light-colored margin on every side, and make sure nothing — borders, captions, page folds — intrudes into it. A module is one of the small squares in the grid, so the margin scales with how big you print the code.

5. Too much data, so the code is dense and printed too small

The more characters you encode, the more modules the code needs, and the higher its version (grid size) climbs. A short URL might be a 25×25 grid; a long URL with tracking parameters, or a vCard packed with contact fields, can balloon to a fine mesh of hundreds of modules. At a fixed print size, each module shrinks — and once a module is smaller than the camera can resolve, the grid smears together and nothing decodes.

The fix: encode less, or print bigger. Shorten URLs and strip unnecessary parameters before generating. If the payload has to be large, increase the physical print size so each module stays comfortably readable from the expected scanning distance — a rough rule is that scanning distance is about ten times the code’s width. For a long password, a WiFi code on a tiny sticker is the classic version of this failure.

6. Physical damage, glare, or a low-resolution photo

Even a perfect code fails if the camera never gets a clean image. Common culprits: a scratched, smudged, or torn printout; specular glare from a glossy laminate or a screen under bright light; a blurry or low-resolution photo where the modules are mush; or a code displayed on a dim, dirty, or cracked phone screen. Each of these adds noise that eats into the same error-correction budget a logo would.

The fix: print on a matte surface to kill glare, keep the code clean and flat, and give it enough light and focus. Bumping the error-correction level up front buys margin against wear and dirt for codes that live in the real world — signage, packaging, table tents.

7. A wrong or broken payload

Sometimes the code scans fine — the phone reads the text instantly — but nothing useful happens. That is a payload problem, not a scannability one. A URL missing its https:// scheme may open as a plain-text string instead of a link. A WiFi code with the wrong encryption type or unescaped special characters in the password (; , : " \\ all need escaping in the WIFI: format) will scan but fail to join. A vCard with a malformed line breaks the contact import.

The fix: generate the payload with a tool that formats and escapes it correctly, then scan the result with a real phone before you publish. If the camera shows the right text but the action misfires, the encoding — not the print — is what to fix. Our WiFi generator handles the escaping automatically, for example.

Check yours

Don’t guess — test. If you already have a code that won’t scan, run it through the scannability checker: it runs a real in-browser decode on the exact image you upload, so you find out whether a scanner can actually read it. If you’re starting fresh, generate a clean one with the QR code generator — its live scannability check flags low contrast, an oversized logo, a thin quiet zone, or a failed decode before you ever hit print.