Published:
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.
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.
| 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) | Label prints too small |
| The right edge or the bottom is missing | Content extends past ^PW/^LL, or the media is
narrower than the file assumes |
Label cut off |
| The barcode prints but no scanner reads it | Module width too small for the resolution, missing quiet zone, or data the symbology cannot encode | Barcode not scanning |
| The whole label is rotated 180°, or one field lies sideways | Three separate switches rotate things: ^PO (whole label),
^FW (all following fields), the orientation letter in
^A (one field) |
Prints upside down |
| Accented or non-English characters print as garbage | Encoding mismatch — the file is UTF-8 but the printer was not told so
(^CI28), or the font has no glyph for the character |
Special characters not printing |
| An extra blank label feeds after every real one | The declared label length does not match the media, or the job carries a
^PQ nobody intended |
Extra blank label |
| The layout is right but everything sits at an offset | A global shift is in play: ^LH, ^LS or
^LT — or ^FT is being read as if it were
^FO |
Content shifted |
| The label comes out completely blank | Structural: unbalanced ^XA/^XZ, a broken
^FS chain swallowing later commands, or data with no
position |
Prints blank |
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.
^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.^FS makes
the following commands part of the previous field's data, so they vanish
from the output instead of erroring.^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.
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.
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.
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).
ZPL is the language Zebra thermal printers understand. How to read the commands, how a label is put together, and the most common mistakes.
Which barcode symbology should I use?EAN-13, Code 128 or QR? Practical rules for picking a barcode based on your data, your space and the scanner that has to read it.
How to preview a ZPL file without a printerA ZPL file is just text — the label only exists once something draws it. Three practical ways to see a ZPL label before it reaches the printer.