troubleshooting · esc-pos
QR Code Not Printing
Quick answer
Determine whether the QR code is absent or merely unreadable. For native ESC/POS QR output, verify model support, command order, length calculation, data encoding, size, and print command. For raster output, verify image loading, monochrome conversion, width, and row data. Always scan the paper result with multiple devices.
Native-command diagnosis
- Initialize the printer.
- Select a supported QR model.
- Set module size and error-correction level within documented ranges.
- Store the exact data using the command’s required length fields.
- Issue the print command.
- Add feed space so the code clears the cutter.
A compatible-looking printer may implement only part of the command family. Test the manufacturer’s example bytes first.
Raster diagnosis
- Wait for the source image to decode.
- Preserve the quiet zone.
- Avoid resampling after binarization.
- Keep the bitmap within the printable dot width.
- Use high contrast and suitable thermal darkness/speed.
If it prints but will not scan
Reduce encoded data, enlarge modules, restore the quiet zone, avoid logos or decoration, and check paper heat damage, wrinkles, low contrast, or scaling. Validate the encoded content itself, including URL scheme and hidden whitespace.
Related content
concept
ESC/POS QR Codes
Learn how ESC/POS printers configure, store, and print QR Codes, and how to choose module size, error correction, payload, quiet zones, and verification.
troubleshooting
Barcode Not Printing
Diagnose missing or unreadable printed barcodes by checking symbology, data rules, ESC/POS commands, dimensions, quiet zones, and media.