ZPL prints a blank label

A ZPL label prints blank when every field lands outside the label, when the format never closes with ^XZ, or when no field has data. Check that fields fit the label in dots, that each label has ^XA and ^XZ, and that each field has ^FD and ^FS.

تم التحديث في 2026-10-20 · Renders made with the OpenZPL engine

What you see

The printer feeds a label with nothing on it, or the preview is empty.

Fields at y = 500 on a 406 dot label

^XA
^FO40,500^A0N,50,50^FDALEX MORGAN^FS
^FO40,580^A0N,40,40^FDAUSTIN, TX 78701^FS
^XZ

Fields inside the label

^XA
^FO40,60^A0N,50,50^FDALEX MORGAN^FS
^FO40,140^A0N,40,40^FDAUSTIN, TX 78701^FS
^XZ

Causes in the ZPL

1. Fields outside the label. The label above was designed for 4 × 6 inches and sent to a 4 × 2 printer: y = 500 is past the bottom edge (406 dots at 203 dpi), so nothing is drawn. The same happens with coordinates for 300 dpi on a 203 dpi printer, or a large ^LH that moves the origin off the label.
2. No ^XZ. Without the end of format the printer keeps waiting for the rest of the label and prints nothing; the next ^XA may merge two labels. The OpenZPL API answers 404 with No labels found in the ZPL and X-Total-Count: 0 in this case, as Labelary does.
3. Fields without data. A field with ^FO and ^A but no ^FD, or an empty ^FD because a template variable was empty, draws nothing. A label made only of such fields is blank; the OpenZPL API answers the same 404.
4. Text the same colour as the background. A ^FR field over nothing, or white text on a white box, renders but can't be seen.

A label with ^XA^XZ and nothing between them is valid ZPL for a printer, which feeds a blank label. The OpenZPL API treats it as an error instead of returning an empty image, so a template bug shows up in your logs.

Causes on the printer

If the preview shows the label and the printer feeds it blank, the ZPL is not the problem:

• Wrong media type. Direct thermal labels need no ribbon; thermal transfer labels print nothing without one. Check the printer's media type setting against your labels.
• Ribbon loaded the wrong way, or ink side away from the label.
• Labels upside down: direct thermal paper is coated on one side only. Scratch it with a fingernail: the side that darkens faces the printhead.
• Darkness at the minimum, or a printhead that needs cleaning.

How to find it

1. Paste the ZPL in the ZPL viewer with the printer's label size and density. If the preview is empty or the API reports no labels, it is the ZPL.
2. Look at the largest ^FO values against the label size in dots (label sizes).
3. Send a known good label, for example ^XA^FO50,50^A0N,50,50^FDTEST^FS^XZ. If that prints blank too, it is the printer or the media.