Skip to content

troubleshooting.md

Latest commit

 

History

History
85 lines (68 loc) · 3.44 KB

troubleshooting.md

File metadata and controls

85 lines (68 loc) · 3.44 KB
Raw

Troubleshooting

A code does not scan

Run Verify with the exact render options you publish:

if err := code.Verify(opts...); err != nil {
	fmt.Println(err)
}

It reports the most common causes directly:

  • Low contrast or light colors. Every dark color, including both ends of a gradient and the finder colors, needs at least 40% luminance contrast with the background. Darken the foreground or lighten the background.
  • Inverted colors. Light modules on a dark background are rejected by many scanners. Swap the colors.
  • Logo too large. Use qr.WithECC(qr.ECCHigh) and a ratio around 0.2; see Logos.

If Verify passes but a printed code does not scan:

  • Too small. Keep each module at least about 0.4 mm wide in print, more for scanning from a distance. Fewer characters or a lower error correction level give fewer, larger modules.
  • No quiet zone. Leave the default margin of four modules, or at least two, clear of other graphics.
  • Too much data. Large versions are dense; shorten URLs, or use WithECC(qr.ECCLow) for codes shown on screens.

A ZXing-based reader fails on a plain code

ZXing and its ports stop looking for finder patterns once they have three candidates. Rarely, under 1% of symbols, data above the bottom-left finder looks enough like a finder to be picked instead, and these readers fail while phone camera apps and this library read the code. Forcing a different mask with WithMask avoids it for a given payload:

for m := 0; m < 8; m++ {
	code, _ := qr.Encode(text, qr.WithMask(m))
	if readsWithYourReader(code) {
		break
	}
}

The library does not do this automatically because it would slow every encode by up to 2.4×; see How it works. With gozxing, the PURE_BARCODE hint also reads these symbols, but it does not accept rounded or circular finders.

Decoding fails on a photo

  • Taken at a steep angle. The decoder corrects perspective up to about 50° of tilt. Beyond that, or for a large code near the edge of a wide-angle photo, hold the camera more squarely to the code.
  • Modules too small. Each module needs about 2 pixels. Move closer or crop the image around the code instead of downscaling it.
  • Large codes. Version 20 and larger codes in photos decode less often than small ones; lens distortion bends their grid. Fill more of the frame with the code and keep it near the center.
  • Very large images. No need to downscale: the decoder searches reduced scales itself and reads modules at full resolution. A 12-megapixel photo takes about 50 ms.
  • Several codes. Only one is read. Crop the image to the code you want.

The text has wrong characters

  • Generated by another tool without an ECI, a byte segment that is not valid UTF-8 is read as Shift_JIS or Windows-1252, whichever reads as more plausible text. If the data is in another encoding, such as GBK, read the raw bytes from DecodeResult.Segments and convert them yourself.
  • For strict scanners that ignore UTF-8 without an ECI, encode with qr.WithUTF8ECI().

The CLI lacks a recent option

The generator tool is released separately and pins a library release, so options added to the library after that release are not flags yet. Check generator version against the CLI guide, use the library directly, or build the tool from a checkout with a workspace (see CONTRIBUTING.md).