Fidelity & troubleshooting
How close is it to the printer?#
The renderer draws ZPL dot for dot as a Zebra printer does: no anti-aliasing, the same positioning rules, and every supported barcode encoded to scan. Placement, sizes and barcodes have been compared with labels printed on a ZM400 (203 dpi), and the rules that differed were corrected.
Known differences:
- Fonts. Zebra's built-in fonts are licensed and not included. Font 0 uses a close substitute, so its letters can differ by a dot or two in width; the bitmap fonts A–H and the OCR fonts are approximations. Positions and line heights match.
- Print darkness.
^MD,~SDand the print speed change how much ink spreads on the paper; the PNG has none. Thin white gaps that the printer fills in (for example text overlapping a barcode) stay visible in the image. - Unsupported commands are reported in
X-Warnings/warningsand skipped; the rest of the label still renders. Not supported or approximated: Data Matrix ECC 000–140 (drawn as ECC 200), QR Model 1 (drawn as Model 2),^GFtype C, BMP and PCX images in~DY, the 2D part of DataBar composites,^FLfont linking,^MUother than dots.
Troubleshooting#
| What you see | Why, and what to do |
|---|---|
| A blank image | The ZPL has no ^XA…^XZ block, or everything is outside the label: check the size and ^LH. |
| The label is upside down | ^PO I prints the label rotated 180° (common in carrier ZPL). See below. |
| Text or barcodes are cut off on the right | The label width is too small, or ^PW limits it. Check {W}x{H} and ^PW. |
| The image is the wrong size | The density in the URL doesn't match the printer, e.g. 8 dpmm ZPL rendered at 12 dpmm. |
Part of a field disappears after a ^ in the text | A ^ inside ^FD starts a new command, as on the printer. Use ^FH and write _5E. (Data merged into a template is escaped for you, see Templates & variables.) |
Text is missing or shows boxes in <zpl-viewer> | The fonts did not load: see SDK › Troubleshooting. |
413 | The ZPL or the label is larger than the server's limits (API › Limits). |
422 | The label could not be rendered within the limits (for example a huge graphic). The message says which. |
503 | The render queue is full. Retry with backoff, or add render workers (Install › Configuration). |
Upside-down labels#
^PO I tells the printer to print the label rotated 180° in the feed direction. Picked up and turned around, the printed
label reads normally, but the image is upside down. To get an image in reading orientation, use POST /v1/render with
"upright": true, or <zpl-viewer> (upright is its default). The PNG route always renders the label as it leaves the
printer.