Why the logo breaks the code
A QR code is a matrix of black and white squares called modules. Every one of them carries data. When you drop a logo on top, you are overwriting some of those data modules with your brand — and unless the scanner can reconstruct the missing pieces, it fails.
The good news: QR codes were designed to handle damage. They include Reed–Solomon error-correction codewords that let a scanner recover the original message even when a portion of the pattern is missing. The question is not whether your logo will obscure data; it will. The question is how much it obscures and whether what remains is enough to reconstruct.
The four error-correction levels
Every QR code is generated at one of four error-correction levels. Each adds redundancy that lets scanners recover from damage:
- L (Low, ~7%) — Smallest code for a given payload. No room for logos. Use only for clean digital displays.
- M (Medium, ~15%) — Safe for digital use with no overlay. Not enough margin for a logo.
- Q (Quartile, ~25%) — Tolerates moderate damage. Works with small logos if you center them carefully.
- H (High, ~30%) — The only level you should use with a logo. The scanner can recover up to 30% of the modules.
QRForge defaults to level H whenever you add a logo in the generator. You can confirm this in the API docs — the errorCorrectionLevel field defaults to H and every example that uses imageOptions keeps it there.
How big can the logo be?
Even at level H, you cannot cover 30% of the code with the logo, because the 30% redundancy is spread across the whole pattern — and if your logo happens to cover a clump of modules that includes part of a format or timing pattern, the code fails regardless of the redundancy budget.
The safe ceiling in practice is around 25% of the code area, which in the generator corresponds to the logoSize slider at 0.25. A logo at 0.30 (30%) occasionally scans but fails often enough to cause support tickets. For a printed campaign you cannot redo, stay at 0.25 or smaller.
The shape of the logo matters too. A circle or rounded square is friendlier than a rectangle because it shortens the longest contiguous run of covered modules. A wide horizontal logo covering a full row of the central data region is far more dangerous than a square logo of the same total area.
Contrast and margin
A logo needs visual separation from the QR pattern. The generator adds a small white (or matching background) margin around the image by default — keep this on. Without it, the scanner's image processor can mistake parts of the logo for data modules and misread adjacent rows.
Choose a logo color that does not match either the light or dark modules of the code. Black-on-white QR with a black logo is fine because the logo reads as 'damage' and the error correction handles it. Black-on-white QR with a white logo defeats the whole purpose; the scanner cannot tell where the logo ends and the quiet modules begin.
On colored or gradient QRs, the safest choice is a white logo on a white inner margin. That gives the decoder a clean 'hole' to ignore rather than a colored region it might interpret as data.
A practical workflow
- 1. Design the code at print size — Render it at the actual printed dimensions, not a shrunken preview. Pixel-count issues that hide at 1000px become unreadable at 2cm.
- 2. Start with the logo at 0.20 — Scan with your phone. Scan again with a second, older phone (iOS 12, Android 10 — these are still widely used). If both pass, push to 0.25.
- 3. Hold the phone at real-world distance — 1 m for posters, 30 cm for menus, 15 cm for packaging. Scanning at 5 cm from a monitor is not a valid test.
- 4. Print a proof — Paper stock, ink, and lighting all reduce contrast. A code that scans flawlessly on screen can fail on a semi-gloss menu. Always test-print before ordering 500 copies.
- 5. Test after lamination — If the final product will be laminated or varnished, the glare from those layers reduces scan reliability. Proof the final finish, not the raw print.
When you need a bigger logo
If the design calls for a logo that genuinely needs to be 30% of the code area — a packaging design with a logo-forward aesthetic, say — there are two safe moves. One: increase the total code size so the absolute area of the logo goes up while the relative portion stays at 25%. Printing the QR at 4 cm instead of 2 cm doubles the usable data area with no change to logo-to-code ratio. Two: encode a shorter payload so the QR has fewer modules and each module is larger, which means each covered module costs you less proportionally. Dynamic QR codes help here — our short slug like /q/abc123 fits in a much smaller code than a full branded URL.
If you keep failing even at 0.20 logo size, the problem is usually not the logo — it is the payload length or print quality. Shorten the URL (dynamic QR), increase the code size, or switch to a higher-contrast ink.
What failure looks like in the wild
When a logo-overlaid QR fails in the field, it usually does so in a specific pattern: newer phones handle it, older phones miss. That is because modern camera apps use machine-learning QR detectors that tolerate more damage than the classic ISO/IEC 18004 decoder. If your test phones are all new, you will miss failures that happen on older devices in your customer base.
Keep a cheap Android from 2019 around for printing tests. If it scans the proof within two seconds, you are safe. If it takes five seconds or you have to reposition, push back to a smaller logo.