Why light-on-dark QR codes fail

The decoder's assumption

ISO/IEC 18004 defines a QR symbol as dark modules on a light background, and decoding pipelines are built on that assumption. The camera frame is converted to greyscale, thresholded, and searched for the three finder squares as dark shapes with the 1:1:3:1:1 ratio. Hand that pipeline a white-on-black code and every module reads as its own negative, the finder patterns it is looking for simply are not there.

The failure is total, not partial. Error correction repairs damaged modules inside a located code; it does nothing when detection itself fails. An inverted code with perfect contrast decodes exactly as well as no code.

Support is inconsistent, which is worse than absent

Some decoders do run a second pass with the polarity flipped:

• Apple's camera app recognises inverted codes and has for years.
• Many Android camera apps do not, and behaviour varies by manufacturer and version.
• Embedded scanner libraries in the ZXing family attempt an inverted pass only when the integrating app explicitly enables it, which most apps never do.
• Hardware scanners at tills and in warehouses are typically configured for standard polarity only.

So an inverted code does not fail everywhere. It fails for an unknowable share of your audience, silently, while working fine on the phone you tested with. That pattern of "scans for me, not for them" is covered more broadly in the not-scanning checklist, but polarity is one of its most common causes.

What to do on a dark design

1. Keep dark-on-light. There is no scanning benefit to inversion, only cost. A standard-polarity code is the correct engineering answer every time.
2. Use a light panel. When the layout is genuinely dark: a black poster, a dark slide, a dark-mode web page, place the code on a solid light card that contains the full four-module quiet zone. The inverted QR codes page covers this pattern in detail.
3. If you must invert, test hostile. Test on several Android devices and any scanner app your audience plausibly uses, not just an iPhone, and expect a share of failures anyway. The technical background is on the colour inversion and polarity spec page.

Whatever you choose, the 40-point contrast rule still applies within the chosen polarity: near-white modules on a mid-grey background fail twice over. Decode the final artwork with the validator before it ships, an inverted code that your own test phone happens to read is exactly the trap this page exists to flag.

FAQ

Do white QR codes on black backgrounds work?

Sometimes, which is the problem. Apple's camera reads them, many Android cameras and most embedded scanner libraries do not. Because you cannot control which decoder your audience uses, treat inverted codes as unsupported and keep modules darker than the background.

Why does my inverted QR code scan on iPhone but not Android?

Apple's camera app runs detection in both polarities. Many Android camera apps and scanner libraries only search for dark modules on a light background, so the inverted code is invisible to them. The fix is to restore standard polarity.

Can error correction save an inverted QR code?

No. Error correction repairs damaged data inside a successfully located code. Inversion defeats the location step itself (the scanner never finds the finder patterns), so there is nothing for error correction to act on.

How do I put a QR code on a dark background properly?

Place a standard dark-on-light code on a solid light panel, sized so the panel includes the full four-module quiet zone on every side. The panel becomes the code's local background and the dark design keeps its look everywhere else.