Guide · OtterQR

Why won't my QR code scan?

A scanner is not a person looking at a picture. It thresholds the image into black and white, hunts for three big squares, and samples the middle of each cell. Almost every failure is one of these five things.

Open OtterQR →

1. Not enough contrast

Two colours that look different to you can land in the same place once a camera has thresholded them. Pastel on cream, dark grey on black, a gradient that fades into the background: all of these read as one flat tone. Keep a real gap in brightness between the code and what is behind it. OtterQR warns as soon as the two get close.

2. A light code on a dark background

The specification assumes dark on light. Modern phone scanners usually cope with the reverse, older hardware often does not, and the cheap scanner at a till is the one that will let you down. If the design really wants a dark background, test it on the oldest device you can find first.

3. No quiet zone

The empty margin around the code is part of the code. It tells the scanner where the pattern ends. Four modules is the standard, which is what OtterQR uses unless you change it, and cropping it away to make the square bigger on a card is a common way to break a code that was working a minute earlier. Also watch what the code is placed on: a busy photograph immediately outside the margin has the same effect.

4. The logo is too big

A QR code can lose part of itself and still be read, because error correction stores the data more than once. At the High setting that tolerance is around 30% of the code, and everything shares it: the logo, a scuff, a fold, a bad angle, poor light. A logo over about a fifth of the width eats most of the budget on its own. Shrink it first when a code with a logo will not read.

5. Round corner markers

The three big squares are how a scanner finds the code before it reads anything. It looks for a run of dark and light in the ratio 1:1:3:1:1 along a line crossing the square, and a circle only gives that ratio through its exact middle. We tested every style combination OtterQR offers against a standard decoder: all six module shapes decoded, and the round and leaf corner markers failed outright. Phone cameras are much more forgiving and usually read them, which is why the styles are still there, with a warning. If a code has to work on unknown hardware, keep the corners square.

Also worth checking

Print size. Aim for about a tenth of the distance it is read from.
Shiny surfaces. Gloss lamination and glass bounce the light straight back into the lens.
Inkjet on porous paper. Ink spreads, cells merge, and a dense code becomes mush. Use a bigger code.
Too much data. A long URL or a full contact card makes a denser grid. Shorten the link, or print it bigger.
The screen it is displayed on. A code shown at low brightness behind a matte protector is harder than the same code on paper.

Test it properly

Test the file you are actually going to use, at the size you are going to use it, with a phone that is not yours. Your own phone has seen the code fifty times while you were making it and its autofocus knows exactly where to look.