# Why light-on-dark QR codes fail

> Most decoders binarise the image expecting dark modules on a light background, so an inverted code reads as its own negative. Support for inverted codes is inconsistent — Apple's camera tries both polarities, many Android cameras and embedded scanner libraries do not. Keep modules dark, or place the code on a light panel.

Source: https://useqr.app/docs/design/why-light-on-dark-qr-codes-fail · Last reviewed 2026-08-21 · UseQR is free forever, MIT licensed, no signup.

---

## 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](/glossary/finder-pattern) it is looking for simply
are not there.

The failure is total, not partial. [Error correction](/docs/spec/error-correction-levels-explained)
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](/docs/troubleshooting/qr-code-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](/docs/design/qr-code-in-a-dark-mode-website) — place
   the code on a solid light card that contains the full four-module quiet zone. The
   [inverted QR codes page](/docs/design/inverted-qr-codes) 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](/docs/spec/qr-code-color-inversion-and-polarity)
   spec page.

Whatever you choose, the [40-point contrast rule](/docs/design/qr-code-contrast-ratio-minimum)
still applies within the chosen polarity: near-white modules on a mid-grey background
fail twice over. Decode the final artwork with the [validator](/validate) 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.

## Try it

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