The code worked in Illustrator. It worked when you tested it on your monitor. Then the postcards came back from the printer and half the people who try it get nothing.
Almost every time, it's one of six things. Here they are roughly in order of how often they're the culprit.
1. It's too small for the distance
This is the big one, and there's real math behind it.
A camera has to resolve individual modules, the little squares. If a module renders smaller than a few pixels in the camera's frame, the decoder can't tell where one ends and the next begins.
The working rule is ten to one. Divide the scanning distance by ten to get the minimum code width.
| Where it lives | Scan distance | Minimum width |
|---|---|---|
| Business card, menu | 6 to 10 in | 0.8 to 1 in |
| Table tent, flyer | 12 to 18 in | 1.2 to 1.8 in |
| Poster at eye level | 3 to 5 ft | 4 to 6 in |
| Retail window | 6 to 8 ft | 8 to 10 in |
| Billboard, building side | 30 ft+ | 3 ft+ |
Then add margin, because the rule assumes ideal light and a steady hand. Neither is true in a restaurant at dinner.
Density matters here too. A code holding a 200-character URL has far more modules than one holding a 20-character short link, and each module is proportionally smaller at the same physical width. If your code looks like static, that's why. Shorten the URL or print bigger.
2. The quiet zone got cropped
The blank margin around a QR code isn't whitespace a designer can reclaim. It's part of the spec. Scanners use that clear border to find where the pattern starts.
The standard asks for four modules of clear space on all sides. Crop tight to the black, or run the code up against a colored background block, and you break the thing scanners use to locate it.
This happens constantly in layout. Someone drops the code into a tight grid cell, or places it over a photo, or butts it against a colored footer bar. It looks cleaner and it stops working.
If you need the code to sit on a colored background, put it on a white or light plate with real margin around it. QR Studio has a plate and quiet zone control for exactly this.
3. Contrast is too low
Scanners need dark modules on a light background. Not "sort of dark on sort of light." Dark.
Things that fail:
- Pastel or mid-tone foreground colors. A soft teal on white looks great in a brand deck and reads terribly at an angle in dim light.
- Light gray on white. Almost guaranteed failure under anything but bright light.
- Two similar colors, like navy on medium blue.
- Any gradient that runs light at one end. Gradients are fine if the lightest stop is still clearly darker than the background.
The fix is boring: keep the background light, and make the foreground genuinely dark. You can still brand it. A deep brand green, a near-black navy, a dark maroon all scan fine. It's the pale end of the palette that kills you.
4. It's inverted
Light code on a dark background is the design trend that causes the most support tickets.
Some scanners handle inversion. Many don't, because the spec assumes dark on light and plenty of decoders never bothered with the inverted case. The iPhone camera usually manages it. A cheap warehouse scanner or an older Android build often won't.
If your design demands a dark background, put the code on a light plate inside it rather than inverting the code itself. Slightly less slick. Works on everything.
5. The substrate is fighting you
Paper isn't the only thing you print on, and the others misbehave.
Glossy stock throws specular glare. Overhead lighting bounces straight into the camera and washes out a section of the code. Matte or satin finish is meaningfully more reliable for anything that will be scanned under store lighting.
Fabric and knit blur module edges. Print bigger than the math suggests, and bump error correction.
Curved surfaces like bottles and cans distort the grid. Keep the code on the flattest available panel and oversize it.
Dark or colored substrates shift your contrast. That kraft paper you love is not white, and a code printed dark brown on kraft has much less contrast than the same file on white.
Ink bleed on uncoated stock thickens modules and closes the gaps between them. If you're printing small on uncoated paper, get a proof.
6. Error correction is set wrong in both directions
QR codes carry redundant data so a damaged code still reads. Four levels:
- L recovers about 7 percent
- M about 15 percent
- Q about 25 percent
- H about 30 percent
Higher correction means more modules, which means a denser code at the same physical size. So it cuts both ways.
Use H when something covers part of the code, mainly a logo, or when it's printing on fabric or a curved surface. Use M as the default for clean print. Use L only when the payload is long, the print is clean and large, and you need to hold density down.
The mistake I see most is people setting H for everything because more redundancy sounds safer, then printing a very dense code at one inch and wondering why it fails. The redundancy didn't help. The extra modules hurt.
The test that actually predicts the outcome
Checking the code on your monitor tells you very little, because your monitor is bright, flat, perfectly lit, and about a foot from your face.
The real test is a print at final size, in the actual lighting, from the actual distance, on at least two different phones. One iPhone and one Android, and if the code is going anywhere retail, borrow whatever scanner they use at the counter.
I put a version of that test in the generator. Before a download runs, QR Studio decodes the finished image again at a ladder of sizes, from 420 pixels down to 80, with a bit of blur added to imitate a camera that isn't perfectly focused. If the code only survives the top of the ladder, the design is too fragile for print and you find out before the file leaves your laptop.
It doesn't replace a physical proof. It does catch the logo that's 5 percent too big and the color pair that's 10 percent too close, which is most of what goes wrong.
Quick checklist before you send to print
- Width is at least one tenth of the intended scan distance, plus margin
- Four modules of clear quiet zone on every side
- Dark foreground, light background, no inversion
- Vector SVG file, not a resized PNG
- Error correction matched to conditions, not just cranked to H
- Matte stock if it'll live under store lights
- Tested on a physical proof from real scanning distance
- Destination URL is short, and dynamic if the print run is expensive
FAQ
What is the minimum size for a QR code? About 0.8 inches for close-range scanning with a short payload. Below that you're relying on ideal conditions.
Why does my QR code work on iPhone but not Android? Usually inversion or marginal contrast. iOS decoding is more forgiving than many Android camera implementations and most dedicated scanners.
Does adding a logo break the QR code? It can. Keep it under about 20 percent of the code width, use higher error correction, and verify before printing. More on that in adding a logo without breaking the code.
Should I use PNG or SVG for printing? SVG. It's vector, so it stays sharp at any size. PNG is for screens, and a PNG scaled up in a layout program gets soft edges that hurt scanning.
Can I round the corners of the modules? Yes, within reason. Rounded and smooth module shapes scan fine because the module centers stay in the right places. Very heavy dot styles with large gaps are where reliability starts dropping, which the verification step will tell you.
Build and verify a print-ready code at gmqr.dev. Free, no account, SVG export included.