Why a QR code will not scan, and the fixes that work

A QR code fails to scan for a handful of reasons. The camera cannot separate the dark squares from the light ones, the code is too small or too dense for the distance, the blank margin around it has been cropped, or part of the pattern is damaged or covered. Check the cheapest causes first: colour contrast and the margin. Both can be fixed in the file before you print again.

Contrast and inverted colours

A scanner looks for dark modules, the squares that make up the code, against a light background. The more the two differ in brightness, the easier the code is to read. The QR code generator measures the contrast between the code colour and the background. It shows a warning when the ratio falls below 4:1, and a separate warning when the code is lighter than its background.

Light-on-dark codes are the risky case. Some scanners cannot read them, so a white code on a black card is a gamble. A pale green code on a white card can look fine to the eye and still fail, because the two colours are close in brightness even though they differ in hue. Use a dark code on a light background, and check the colours in the light where the code will be seen.

The quiet zone

A QR code needs a blank margin of light space around the pattern, called the quiet zone. The standard width is four modules, where a module is one square of the code. The scanner uses the margin to find the edges of the pattern. A code printed edge to edge on a flyer, or cropped tightly in a design program, often loses its margin, and then it may not scan at all, even when it looks perfect.

The generator sets the quiet zone to four modules, the standard width, and lets you widen it up to 10 but not narrow it. A wider margin helps when the code sits close to busy artwork. On a coloured poster, keep a light panel behind the whole code, margin included, rather than letting the artwork run up to the pattern. Check the margin again after you resize the image in another program, because resizing can crop it.

Size, data and error correction

A QR code is a grid, and more data means more squares. A short link fits in a sparse grid. A long link with tracking parameters makes a denser grid, with smaller squares, and the camera has to resolve each square at the distance you scan from. Two fixes help: print the code larger, and shorten the content. The guide to removing tracking from links explains how to strip the extra text from a link.

Test at the distance people will actually use. A code that scans from 10 cm on a desk may fail from a metre away on a shop window.

Error correction adds redundant data, so that a damaged or covered part of the code can still be read. The standard levels are L, M, Q and H. They recover roughly 7%, 15%, 25% and 30% of the codewords respectively. The generator uses M by default, and H is the choice for a logo over the centre.

Higher error correction is not free. It adds more redundant squares, so the same content needs a denser and larger code. Raise the level only when the code will be damaged or covered. Raising it does not fix low contrast, and a denser code can be harder to scan at a distance.

Checking a code before you print

1. Generate the code at the size you plan to print. The generator offers SVG as well as PNG, and an SVG stays sharp at any print size.
2. Check that the contrast warning is clear, and that the margin is part of the file.
3. Print a test at the real size, on the paper you will use, and scan it in the light it will be seen in.
4. Scan it from the distance people will use, and from a little closer and a little farther.
5. If it fails, change one thing at a time: contrast, then margin, then size, then the content.

Edge cases

• Glare. A glossy laminate or a window behind the code can wash out the light squares. Angle the code away from the light, or print it on matte paper.
• Curves. A code wrapped around a bottle, a mug or a curved sign bends out of shape, and the grid no longer lines up. Print on a flat surface, or make the code large enough that the bend matters less.
• Wear. Creases, scuffs and rain can break up squares faster than error correction can cover them. A clear matte cover protects a printed code without adding glare.
• Screens. A code on a phone or monitor needs enough brightness, and the screen should face the camera. A tilted screen can reflect the room and wash out the code.
• Static or dynamic. A static code holds its content inside the pattern, so it does not depend on a service staying online. A code that points to a redirect service stops working when that service does. Static and dynamic QR codes explains the difference.
• Wi-Fi codes. A Wi-Fi code uses the same QR format, so the same causes apply. The Wi-Fi QR card builds a printable card for guests to scan with a phone camera. Most phones made in recent years join from the camera app, while older phones may need a scanner app.
• Lens and zoom. A smudged lens causes blur that looks like a bad code. Clean the lens first, and step back rather than using digital zoom, which loses detail.