Guide · Troubleshooting

Thermal printer troubleshooting

Find your symptom below. Most fixes take under a minute.

Last updated: October 2026

The USB picker is empty

Check the printer is switched on and the cable is plugged in directly (not through a hub). Try another cable — some USB cables carry power only.
Use Chrome, Edge or Brave. Safari and Firefox have no WebUSB, so there is no picker at all.
On macOS or Linux, remove the printer from the system printer list (Printers & Scanners / CUPS) and replug it.
On managed work or school computers, an administrator policy can disable WebUSB.

"Access denied" or "Unable to claim interface"

Another driver owns the printer. On Windows, replace the USB printing driver with WinUSB using Zadig; on Linux, unload the usblp module and add a udev rule; on macOS, remove the printer from Printers & Scanners. Step-by-step instructions are in the setup guide. Also close other browser tabs or apps that might already be connected to the printer.

Test print works, image prints garbage

Diagonal stripes or random characters usually mean the image is wider than the head. Switch paper width from 576 to 512 dots, or to 384 for 58 mm printers. See paper width explained.
If even small images print as characters, the printer may not support the GS v 0 raster command. See how raster printing works.

Nothing prints at all, but connect succeeded

Check the paper is loaded with the coated (thermal) side facing the print head. Scratch the paper with a fingernail: the side that turns dark is the printable side.
Close the printer lid firmly; most models refuse to print with the lid open and blink an error LED.
Some printers expose more than one USB interface. Disconnect, replug and connect again so the correct bulk endpoint is selected.

Image prints too dark or blotchy

Thermal paper darkens more than a screen suggests. Increase brightness by 10–25, try Atkinson instead of Floyd–Steinberg, and make sure the paper is genuine thermal paper rather than old stock — paper exposed to heat or sunlight greys over. More in the dithering guide.

Image prints too light or faded

Lower brightness or raise contrast; for logos use Threshold and move the slider up.
The print head may be dirty. Switch the printer off, let the head cool, and wipe it gently with a cotton swab and isopropyl alcohol.
A weak power supply causes faded, uneven lines on dark images. Use the original adapter, not a USB-powered hub.

Horizontal white lines through the image

A consistent thin line at the same position on every print means a damaged or dirty dot on the print head. Clean it first; if the line remains, the head element is likely broken.

The paper isn't cut

Enable Cut paper after print. Many cheap printers have only a tear bar and no cutter; the cut command is then ignored. If your printer has a cutter but ignores GS V B, it may expect a different cut variant.

Printing stops halfway through a long image

The paper roll ran out or the printer overheated — long dark images heat the head; let it cool and print again.
Keep the browser tab in the foreground until printing finishes; some systems throttle background tabs.