Paste code or load the sample — the result appears below, with the line and severity of each finding.
2Result
Health report
Thermal label problems are diagnosed backwards: you see the
physical output, then work back to the line of ZPL that caused it. This page
is the triage step — match what the printer actually did, get the usual
cause, then follow the check that confirms it. Every symptom below links to
a full walkthrough.
Start from the file, not the printer
The instinct is to change a printer setting, print again, and see. That
costs labels and hides the cause: a setting change can mask a file problem
for one job and let it come back on the next printer. The ZPL is text you
can read, and most failures are visible in it — declared size, coordinates,
field terminators, orientation letters. Read the file first; touch the
printer only when the file is proven clean.
Symptom → likely cause
What you see
Usual cause
Walkthrough
Everything printed, but far too small on the media
The file was written in dots for one resolution and sent to a printer
with a different one (203 vs 300 dpi)
A browser preview renders the same commands a printer would draw, so it
settles a large class of questions without wasting media: whether the
content fits the declared size, whether coordinates land where you think,
whether a barcode's data is encodable, whether ^FW and the
per-field ^A orientations do what you expect, and whether the
command stream is structurally sound.
It cannot prove the physical layer. Print orientation applied inside the
printer (^PO), top-of-form offset (^LT), media
tracking and gap sensing, darkness and speed, ribbon and head condition,
and RFID encoding all happen after the image is composed. A preview that
looks perfect narrows the problem to that layer — which is useful
information, not a failure.
The preview is right but the paper is wrong: a checklist
"It looks fine in the viewer and prints blank (or rotated, or tiny)" is one
of the most common questions about ZPL. Work down this list in order — each
step rules out one layer between the file and the head:
Does the preview use the printer's density? A file
written for 203 dpi looks correct at 8 dpmm and prints at two-thirds
size on a 300 dpi head — see label prints too
small.
Does the job reach the printer raw? A Windows or CUPS
driver can rasterise, scale, rotate or wrap the job; ERP and shipping systems
that print through a driver are the usual source of rotated carrier labels —
see printing ZPL without a driver.
Is the printer interpreting ZPL at all? In dump
(diagnostic) mode it prints the received commands as text, and an EPL-only
printer turns ZPL into garbled output — see printer prints gibberish.
Are settings stored in the printer overriding the file?
Orientation (^PO), top offset (^LT), label shift
(^LS) and print width can be saved in the printer's configuration
(^JUS); a saved value applies to every job that does not set it
itself — see label prints upside
down and content shifted.
Is the media sensed correctly? Blank or skipped labels
with a correct preview point at gap/mark sensing and calibration — see extra blank label.
Did it go to the printer you think? A queue or IP that
now points at a different device produces "nothing happened" — see label printed on the wrong printer.
Three checks that catch most of it
Does the file declare its size, and does that match the media?^PW and ^LL are in dots, not inches or millimetres.
A 4-inch label is 812 dots at 203 dpi and 1218 at 300 dpi.
Is every field closed? A missing ^FS makes
the following commands part of the previous field's data, so they vanish
from the output instead of erroring.
Is anything shifting or rotating globally? Search the
file for ^LH, ^LS, ^LT,
^PO and ^FW before you inspect individual
fields — one of them explains most "everything moved" reports.
Paste a label into the ZPL viewer to
run the structural checks and see the rendered result in one step.
Frequently asked questions
Where do I start when a ZPL label prints wrong?
Start from the file, not the printer. Declared size (^PW/^LL), coordinates, the ^FS chain and orientation letters are all readable text, and most failures are visible there. Changing a printer setting can mask a file problem for one job and let it return on the next printer.
Can a browser preview prove why my label prints wrong?
It settles the composition layer: whether content fits the declared size, whether coordinates land where you expect, whether barcode data is encodable, and whether the command stream is structurally sound. It cannot prove the physical layer — ^PO print orientation, ^LT top offset, media tracking, darkness, ribbon and head condition all happen after the image is composed.
What are the fastest checks on a broken ZPL label?
Three: does the file declare a size that matches the media (^PW/^LL are in dots — 812 at 203 dpi for 4 inches, 1218 at 300 dpi); is every field closed with ^FS; and is anything shifting or rotating globally (^LH, ^LS, ^LT, ^PO, ^FW).
