Why your QR code is not scanning, and how to fix it

A QR code either scans instantly or it feels broken. There is very little middle ground, which makes debugging frustrating: the code looks fine to you, and the phone just sits there. In practice almost every failure comes down to one of six causes, and you can work through all of them in about a minute.

1. Not enough contrast

A scanner does not see colour. It converts the camera image to greyscale and looks for a threshold between light and dark modules. Two colours that look completely different to you — a mid-blue on a mid-green, say — can land within a few percent of each other in luminance and become indistinguishable.

The safe rule is a contrast ratio of at least 4.5:1 between the dark modules and the background, and ideally much more. Near-black on white is the reference case for a reason. If you want brand colours, put them on the dark modules and keep the background white or very close to it.

2. The code is inverted

Light modules on a dark background looks striking, and a minority of scanners handle it. The QR specification assumes dark-on-light, and many decoders — including some built into older phone cameras and most industrial scanners — will not attempt the inverse. If your design calls for a dark background, put the code inside a light panel rather than inverting it.

3. The quiet zone was cropped

The quiet zone is the empty margin around the symbol. The specification requires four modules' worth on all sides, and it is not decorative: the decoder uses it to find where the symbol starts. This is the single most common failure in print, because a designer sees empty space and tightens the layout.

4. Too much data in one symbol

The more you encode, the more modules the symbol needs, and the smaller each module becomes at a fixed physical size. A URL of 30 characters produces a comfortable, chunky grid. The same code carrying a 900-character vCard becomes a dense mesh that needs a much better camera and much steadier hands.

• Shorten URLs before encoding — drop tracking parameters, and use the site's own short path if it has one.
• For a vCard, include name, phone, email and company. Leave out the postal address and the note unless you genuinely need them.
• If the payload is over roughly 300 characters, consider linking to a page instead of encoding the content directly.

5. Printed too small for the scan distance

The working rule is that a QR code can be scanned from about ten times its own width. A 2 cm code is comfortable at 20 cm — fine on a business card or a table tent. A poster read from three metres away needs a code around 30 cm wide.

That rule assumes a modest amount of data. A dense symbol needs to be physically larger to keep each module above the camera's resolving limit. When in doubt, print a test at the real size and try it with the oldest phone in the office, not the newest.

6. A logo that ate too many modules

Error correction lets a QR code survive partial damage, which is why you can drop a logo in the middle at all. Level H recovers from roughly 30% of the symbol being obscured. But that 30% is a budget shared with print defects, glare and creases — spend all of it on a big logo and there is nothing left for the real world.

Keep the logo under about 20% of the code's width, leave the clear-space option enabled so it sits on a solid patch rather than on top of data modules, and always test the printed result rather than the screen preview.

A one-minute diagnostic

1. Open the code on a screen at full size and scan it. If that fails, the problem is in the code itself — contrast, inversion or density.
2. If the screen works but print does not, measure the quiet zone and the physical width.
3. Try a second scanner app. If one app works and another does not, you are probably relying on inverted colours or an unusual payload format.
4. Remove the logo and re-test. If it suddenly works, reduce the logo size and raise error correction to H.
5. Halve the payload and re-test. If that fixes it, the symbol was simply too dense for the print size.

Work through those five checks and you will find the cause almost every time. The underlying lesson is that a QR code is an optical system, not just an image: it has to survive the camera, the lighting and the paper, and the margins for all three are set at design time.