Troubleshooting

By Alexis Rios-Negron · ThermalPrint 0.12.0

Find your symptom in the table, or jump to a detailed section below. If nothing here helps, open an issue and include your ThermalPrint version (click it in About to copy it), your package type, and your printer model. Leave out personal addresses and tracking numbers.

Quick table#

Symptom	What to check
No printers are listed	See below.
The Print button is gray	See below.
A PDF will not open	Install PDFium or Poppler's `pdfinfo` and `pdftoppm` (the packages include Poppler). Re-export encrypted or damaged PDFs.
Print all is blocked	Select and review each label in the queue. Every entry needs its own review.
The label is too small	Crop away empty space first, then compare Fit within paper and Actual size. Check the paper size.
Edges are cut off	Check the printer media matches the labels, try a small margin, and use the alignment offset.
Everything is shifted to one side	Use the alignment test and offset.
Extra blank labels or a banner page	See below.
CUPS accepted the job, nothing printed	Check Job status, the printer's power, cable or network, label roll, and the CUPS queue state.
A barcode will not scan	See below.
Text is missing or cut off in a design	Text does not wrap. Make the box bigger, use the `Enter` key for new lines, or reduce the font size.
Text is cut off even with a big box	Tick Wrap long lines or Shrink to fit the box in the text settings.
My font is not used on another computer	A design stores only the font name. Install the same font file there with the T button in the text settings.
Print sheet is gray	The selected printer does not list A4 or Letter. Save the sheet as a PDF and print it from another program, or choose a printer that offers the paper.
A GS1 barcode is refused	Read the red message under the barcode settings: a wrong check digit, a bad date, or a variable-length field that is not last in a GS1 Data Matrix. See the GS1 section.
I closed ThermalPrint by accident	Start it again: unsaved changes are offered back at the top of the Label Designer. See the recovery copy.
`.thermalprint` files show a generic icon	For the Debian and Fedora packages, update to 0.6.2 or later (it adds a preview thumbnail that works with every icon theme), restart the file manager (`nautilus -q`), and look again. A file that was already shown may keep its old icon for a while; renaming it or restarting the session refreshes it. For the Snap, run the register-mime helper again: it copies the icon into your user icon folders, including the folder of your current icon theme, because themes such as Zorin and Adwaita show their own generic file icon unless the theme folder has the icon. Then restart the file manager (`nautilus -q` in a terminal) or log out and in.
A label disappeared from the queue after printing	The Move printed labels to a Processed folder option is on. The label was printed and its file is in the `Processed` folder inside your watch folder. Untick the option under Watch a folder to keep printed labels in the queue.
Cannot read the watch folder, still trying · …	The folder or its drive is unavailable right now. Nothing is lost: watching resumes by itself and a message tells you when the folder is readable again.
Undo did nothing	Undo only works for labels still in `Processed`. If a file was moved again, deleted, or a new file now has the original name, it is left alone. Use Add from Processed… instead.
Print all printed fewer labels than expected	With Keep going if a label fails on, failed labels are skipped and stay in the queue. Read the message (or open Messages) for why the first one failed, fix it, and press Print all again. With the option off, the batch stops at the first problem.
The Print all button prints labels I did not review	Skip review for automatic crops is on. Untick it to review every label again.
The watch folder switched itself off	The folder moved or cannot be opened. Choose it again, or press Turn watching back on. In the Snap, see folders.
F1 or Help does nothing	ThermalPrint hands the link to your default web browser. Check that one is set, or open the manual directly.

No printers are listed#

Make sure the printer is on and connected, and that it appears in your desktop's printer settings.
In a terminal, run lpstat -p. If it lists your printer, press Refresh printers in ThermalPrint.
If lpstat says it cannot connect, the CUPS service is not running. Start it with sudo systemctl enable --now cups.
Snap: check snap connections thermalprint and see If printing is not connected.

You can still export files with no printer; see Exporting.

The Print button is disabled#

Printing needs all of these. The status notice in Print Center tells you which one is missing:

The label has finished rendering.
A label with a changed crop has been reviewed (I checked the crop and barcode edges).
A printer is chosen.
A media size the printer offers is chosen. If the driver offers none, set the printer up for label stock in your system's printer settings.
Nothing is clipped: the content fits the paper.

Some printer systems can print a banner or job sheet before and after each job. On a label roll each banner uses up a label. ThermalPrint turns banner pages off for every job it sends. If you still get extra labels:

Check whether the labels are really blank pages from the printer's own settings, such as a "gap detect" or "page length" option set for a different label size. Run the printer's calibration (usually a button or a button combination on the printer).
Check that the printer media matches the label size. A taller media size than the label feeds extra labels.
Print one label and look at the CUPS job in your printer settings to see how many pages it has. A single page means the printer feed is the cause.

Barcodes that do not scan#

Turn off Black-and-white threshold in Import & Convert unless you really need it.
Check the print is dark enough: raise the printer's darkness or speed setting in its own driver.
Widen the barcode. Thin bars are the usual cause.
Leave empty space on both sides.
Use the right type for your scanner; see the Barcode reference.

Content looks blurry or jagged#

Set Rendering DPI to the printer's real resolution (usually 203 or 300). If you enlarged a small low-resolution image, ThermalPrint warns that detail cannot be recovered; use a bigger source.

Messages you may see#

Message	Meaning
Printing blocked: content would be clipped	The label does not fit the paper. Use Fit, rotate, a smaller scale, or larger paper.
Select an advertised printer media size	Pick one of the media choices the printer offers.
Printer selection has changed. Refresh printers and try again.	Press Refresh printers and choose the printer again.
CUPS rejected the job: …	The printer system refused the job. The text after the colon comes from CUPS and usually says why.
Output is … mm; printer media is … mm	The label size differs from the media. Use Match output to printer media or choose matching media.
Printing is not connected. In a terminal run: sudo snap connect …	Run that command. See Using the Snap.
A label did not print automatically	Read the message (or open Messages). The usual reasons: it needs a review, it has several pages, its name does not match Only files named (this one is silent), automatic printing is paused, or no printer or media is chosen. The label is in the queue, so you can print it by hand. See Printing labels automatically.
Automatic printing is paused · …	A print failed or the printer is not ready, so it stopped to avoid repeating the problem. Fix the cause, then press Resume auto-print beside the Watching line.
Automatic printing is limited to N labels per minute	A burst of files hit the limit under Most per minute. The rest are only waiting; raise the limit if you want faster printing.
Automatic printing started again after I restarted the app	Pause is not remembered. Untick Print labels automatically to turn it off for good.
Printed, but could not move a label to Processed · …	The label printed, but its file could not be moved. Check that you can write to the watch folder. The label has already left the queue.
Watch folder is off · …	The reason follows the dot. Choose a readable folder.

Getting diagnostic details#

Start ThermalPrint from a terminal with extra logging:

RUST_LOG=thermalprint=debug thermalprint

For the Snap, use RUST_LOG=thermalprint=debug snap run thermalprint. Logs may include file paths, so read them before posting.