# QR code on a busy background: diagnosis and the white-card rule

> A busy background breaks a QR code by collapsing contrast locally: the telltale symptom is inconsistency, scanning from some angles, phones or distances but not others. Confirm by testing the same code on plain white, then fix it with a solid light card carrying the full four-module quiet zone.

Source: https://useqr.app/docs/design/qr-code-on-a-busy-background · Last reviewed 2026-08-21 · UseQR is free forever, no signup.

---

## The symptom is inconsistency

Total failures have simple causes: wrong polarity, missing quiet zone, dead link.
Background interference looks different. If several of these sound familiar, the
background is the prime suspect:

| Symptom | Why interference causes it |
|---|---|
| Scans up close, not at distance | at distance, fewer pixels per module, noisy regions tip first |
| Scans from some angles only | glare and shadow move the local contrast above and below threshold |
| Phone A reads it, phone B never does | decoders differ in adaptive thresholding aggressiveness |
| Worked on screen, fails in print | print compressed the difference between texture and modules |
| Long focus-hunt, then sometimes success | detector keeps rejecting candidate regions that half-match |

The mechanism: decoders binarise the image with thresholds computed over local regions.
A background that swings between light and dark across the code makes some regions
threshold wrongly: modules over dark texture read light, or texture reads as modules.
[Error correction](/docs/spec/error-correction-levels-explained) absorbs a little of
this, which is exactly why the failure is partial and maddening rather than clean.

## The two-minute isolation test

1. Decode the flattened final artwork with the [scanner](/scan). If it fails digitally,
   you have reproduced the problem without printing anything.
2. Regenerate the same payload as a plain dark-on-white code and test it in the same
   physical spot at the same distance. Passing here acquits the code and convicts the
   placement.
3. Run the styled version through the [validator](/validate); if the *bare* styled
   export verifies but the composition fails, the background is the only variable left.

If instead the code fails everywhere, work through the broader
[not-scanning checklist](/docs/troubleshooting/qr-code-not-scanning-checklist): the
fault is in the code, not behind it.

## The white-card rule

The fix is the least glamorous tool in QR design: an opaque, solid, light panel behind
the code. To be sufficient it must cover:

- the symbol itself,
- the full **4-module [quiet zone](/glossary/quiet-zone)** on all four sides,
- ideally 1–2 further modules of margin for print tolerance and looks.

White is optimal; any light solid works if it keeps a
[40-point luminance difference](/docs/design/qr-code-contrast-ratio-minimum) under the
darkest modules. Partial measures (semi-transparent panels, feathered edges, a card
that hugs the modules with no quiet zone) reintroduce the same failure at reduced
intensity. If the design genuinely cannot host a card, the gradated alternatives
(dimming the region by a measured amount, relocating the code to a calm area of the
layout) are worked through with numbers on
[QR codes on photos and textures](/docs/design/qr-codes-on-photos-and-textures), and
placement strategy more broadly on
[QR code placement in a layout](/docs/design/qr-code-placement-in-a-layout).

The card also future-proofs: backgrounds get re-art-directed, seasonal variants swap
in new imagery, and a code with its own ground survives all of it unchanged.

## FAQ

### How do I know the background is why my QR code fails?

Inconsistency is the signature: some phones, angles or distances work while others do
not. Confirm by testing the identical payload as a plain black-on-white code in the
same spot; if that scans reliably, the background is the difference.

### Does the white box behind a QR code have to be white?

No, but it must be solid, opaque and light, at least 40 luminance points above the
module colour. White maximises margin and is the default for a reason; a light brand
tint that passes the arithmetic is fine.

### How big does the backing card need to be?

The code plus its four-module quiet zone on every side, minimum. A card that crops the
quiet zone trades one failure for another; an extra module or two of margin costs
little and absorbs print drift.

### Why does error correction not handle a busy background?

It does, partially, which is why the code half-works. Error correction budgets for a
limited share of misread modules, and a busy background can corrupt more than the
budget while leaving enough intact for occasional lucky scans.

## Try it

- https://useqr.app/validate
- https://useqr.app/scan
- https://useqr.app/url