Why Your QR Code Won't Scan and How to Fix It

A QR code that refuses to scan is almost never a mystery. It is usually one of seven physical problems, and you can identify which one by watching how the code fails. Does the phone lock on instantly at 8 cm but lose it at arm's length? That is sizing. Does it work on your flagship phone and fail on your colleague's three-year-old handset? That is contrast or module size sitting right on the edge of the threshold. Does the exported PNG scan perfectly on screen and die the moment it hits paper? That is the printer.

Start with the failure mode, not with the generator settings. Re-encoding the same content at a different error correction level fixes almost nothing, which is why people waste an afternoon on it.

The 10:1 rule, and where it actually comes from

The rule of thumb you will see repeated everywhere: your scan distance should be no more than about ten times the width of the code. A 2 cm code on a business card is good for roughly 20 cm. A 20 cm code in a shop window is good for about 2 m.

Two honest caveats. First, this ratio is not in ISO/IEC 18004. The standard defines symbol geometry and error correction; it says nothing about a distance-to-size ratio. The 10:1 figure circulated through industry sizing guides and printer application notes, and it stuck because it is conservative and easy to remember.

Second, and more useful: the real constraint is not the overall width of the code but how much of the sensor each module lands on. A version 1 code (21×21) printed at 2 cm has modules just under 1 mm wide; a version 10 code (57×57) at the same 2 cm has modules around 0.35 mm. The second fails long before the first, which is why "make it bigger" does not always save a dense code — sometimes you have to shorten the URL instead.

Contrast: the problem is usually not the black

Scanners do not read colour. They convert the image to greyscale, threshold it into light and dark, and what matters is the luminance gap between the two states — not how dark your brand colour looks to your eye.

Pure red is the classic trap. #FF0000 has a relative luminance of about 0.21, which is mid-grey once the camera thresholds it, close enough to the cut-off point that the result depends on the phone, the white balance and the lighting. Orange and mid-blue on white are risky the same way. Dark navy, near-black and dark green are fine.

Inverted codes — light modules on a dark background — work on most modern phone cameras but still fail on a meaningful share of older handsets and dedicated hardware scanners. Keep dark-on-light for anything permanent, and keep the symbol off photographs, gradients and patterned backgrounds.

The quiet zone is part of the code, not decoration

The blank margin is specified at four modules on every side. It is what lets the scanner find the symbol's edge. When a designer crops it to make the layout tidier, or when a code is placed hard against a border, a dark image edge or another printed element, the finder patterns stop being distinguishable from the background and the scan simply never starts.

Two rules that prevent most of this: never let the margin become a different colour from the light modules (a white code on a coloured card is fine as long as the margin is white too, not the card colour), and never place a code within 4 mm of a hard dark edge.

In practice you can often get away with two modules of margin and many encoders default to that. When you are printing at the lower end of the size range, take the full four.

When the code is too dense for the size you printed

Long URLs are the most common cause of an unscannable small code. Every character you add pushes the data into a higher version, which adds four modules to each side, which makes each module smaller at a fixed print size.

A 30-character URL encoded at error correction level M lands around version 3 (29×29). Add a long query string with UTM parameters and you can easily reach version 7 or 8 (45×45 to 49×49) — a code that needs to be roughly twice as wide to be read at the same distance. If the print size is fixed and the code will not scan, cutting the URL is a more reliable fix than anything else on this page. Our URL QR code generator shows you the version you are producing, which is worth watching when you are sizing for a business card.

Print problems: dot gain, gloss and fabric

On absorbent stock, ink spreads. Uncoated paper typically gains 20–30% on halftone dots, and while a QR code is solid rather than screened, the same spread happens at module edges: dark modules merge, light ones shrink, and the scanner sees something it cannot resolve. That is why a file that scans on a monitor dies on paper.

In order of effectiveness: shorten the data so modules get larger, print larger, use coated stock, and supply a vector PDF so the printer is not resampling your modules. Glossy lamination turns a code into a mirror under shop lighting — matte costs almost nothing and removes a whole class of failure. Thermal receipts are their own problem, since direct thermal paper darkens with heat and light; print those on demand, not in batches.

Curved and reflective surfaces

A label wrapped around a bottle or cup is bent in one axis. Perspective correction handles some of that, but it degrades fast as the code grows relative to the curve's radius. Keeping the code small with a generous quiet zone helps more than you would expect, because the outer modules distort most. On metal, laser marking often produces low contrast — a light mark on dark anodised aluminium usually reads better than the reverse.

The camera side of the problem

Sometimes the code is fine and the phone is not. A smudged lens is the most common cause of a camera that hunts for focus and never settles. Low light, a nearly flat battery and Low Power Mode all slow the camera pipeline enough that autofocus feels broken. If a code scans on one phone and not another, test on the oldest device you can borrow before reprinting anything.

Symptom to fix: the short version

Symptom	Most likely cause	What to do
Nothing recognised at all, from any distance	Quiet zone cropped, or code touching a dark border	Re-export with a 4-module margin in the same colour as the light modules
Works on one phone, fails on another	Contrast or module size sitting near the threshold	Darken the foreground; increase module size; retest on an older handset
Scans at 10 cm, fails at 30 cm	Code too small for the scan distance (10:1 breach)	Print larger, or move the code closer to where people stand
Scans indoors, fails in daylight	Glossy laminate or screen glare washing out the image	Matte laminate, or relocate away from direct light
Fine on screen, dead on paper	Dot gain merging modules, or bitmap resampling	Send vector PDF, use coated stock, shorten the URL, print larger
Works flat, fails on the bottle or cup	Cylindrical distortion	Shrink the code relative to the curve, or move it to a flat panel
Camera hunts for focus and will not settle	Dirty lens, low light, or a throttled camera on a low-battery device	Clean the lens, add light, disable Low Power Mode and retry
Scans, but opens a 404	Case-sensitive URL path altered, or a trailing character dropped	Use lowercase paths; test the exact decoded URL in a browser
Worked last month, dead now	Faded thermal print, sun-bleached ink, or scuffing	Reprint on demand; switch to pigment ink or a laminated label

Frequently asked questions

Does a higher error correction level make a badly printed code scannable?

Only for damage, not for poor reproduction. H helps when part of the symbol is scratched, covered by a logo or dirty. It does nothing for dot gain, low contrast or insufficient size, because those corrupt every module uniformly rather than a random subset. If the print is bad, fix the print.

How big does a QR code need to be on a business card?

2 cm (about 0.8 in) works, provided the content stays in a low version. A vCard with a long job title and three phone numbers can push you past version 10, at which point 2 cm is too small — trim the fields and re-check. Full table in our print sizing guide and QR codes on business cards.

Can I put a QR code on a coloured background?

Yes, as long as the contrast between light and dark modules stays wide and the quiet zone is flat and unprinted. A pastel background behind a black code is fine. A mid-tone brand colour with grey modules is not.

Why does my code scan on Android but not iPhone, or the reverse?

The two platforms use different binarisation and detection pipelines, and they disagree most often on inverted codes, coloured codes and very dense symbols. When they disagree, the code is marginal. Treat the failing platform as the spec and adjust until both work.

Is a white QR code on a black poster a bad idea?

It scans on most current phones, so it will probably work for a poster with a short lifespan. For anything permanent — signage, packaging, a plaque — use dark modules on a light background. A meaningful number of hardware scanners and older camera apps simply do not invert.

My code scans but slowly. Is that a problem?

Yes, in practice. Beyond about two seconds of hunting, a large share of users assume the code is broken and give up. Slow acquisition is a symptom of the same marginal conditions listed above — treat it as a warning that you are near the edge.

Do I need to reprint if only part of the code is scratched off?

Not necessarily. Error correction is designed for exactly this. If you encoded at level Q (25%) or H (30%), a scuffed corner or a coffee stain will usually still decode. Try it before you reprint; if it fails, the damage exceeds what the redundancy can reconstruct.