Diagnostics Reference
Every diagnostic code the ZPL engine can report, with severities, examples, and where they surface
The rendering engine reports what it skipped, fell back on, or failed to render as diagnostics. Diagnostics never alter rendering — a label renders identically with or without them, matching physical-Zebra best-effort behavior. They only make the printer's silent decisions visible, so "my label looks wrong" is answerable without printing it.
Where diagnostics surface
| Surface | How you get them |
|---|---|
| API (the Labelary-compatible layer) | X-Warnings response header when the request sends X-Linter: On (capped at 20) |
| Online viewer | Inline panel below the preview + editor squiggles; grouped so a warning repeated across a multi-label file reads as one line |
| Desktop app | The same shared panel and squiggles |
The warnings arrive with the render — you never render twice to get them.
Severities
| Severity | Meaning |
|---|---|
info | Notable-but-normal behavior (e.g. an explicitly skipped argument slot replaced by a default) |
warning | The render succeeded, but possibly not as intended (skipped command, trimmed value, fallback) |
error | A piece of output could not be produced (barcode/graphic generation failure) |
A render that succeeds with warnings keeps succeeding — warnings are
never promoted to failures. info-level diagnostics appear in the
viewers but are excluded from the API's X-Warnings header.
Codes
Codes are a stable contract — new codes may be added, but existing codes will not be renamed.
| Code | Default severity | Emitted when | Example message |
|---|---|---|---|
UNKNOWN_COMMAND | warning | The command name is not documented ZPL | This ZPL command does not exist and was ignored |
UNSUPPORTED_COMMAND | warning | Documented ZPL the renderer does not implement yet | command "^KL" is valid ZPL but is not supported by this renderer yet; it was skipped |
ARGUMENT_MISSING | info | An argument slot was explicitly skipped (10,,30) | argument 2 of ^FO omitted; default used |
ARGUMENT_TRIMMED | warning | Trailing garbage trimmed per ZPL printer behavior | Value '10abc' is not a valid number; suffix 'abc' was ignored |
ARGUMENT_INVALID | warning | Argument could not be interpreted; fallback used | Value 'ab' is not a valid number and was ignored |
ARGUMENT_OUT_OF_RANGE | warning | Argument outside its valid range; fallback named | Value 0 is less than minimum value 1; used 1 instead |
RENDER_ERROR | error | Barcode / graphic generation failed at render time | failed to render Code 128 barcode (^BC): ... |
RESOURCE_MISSING | warning | A stored object is referenced but does not exist | ^XG references image "R:LOGO.GRF" which was never stored (no matching ~DG); field skipped |
Notes:
- Case matters in ZPL. A lowercase command like
^foreportsUNKNOWN_COMMANDwith a hint:... ZPL commands are case-sensitive — did you mean "^FO"? - Out-of-range messages always name the fallback that was actually
applied:
; used 10 insteadwhen the engine clamps,and was used as writtenwhen it keeps your value. - Idiomatic trailing omissions (
^FO10,20with no third argument) are deliberately silent — that is normal ZPL, not a mistake.
Positioning
Each diagnostic points at its source, where known:
- the command as written, including prefix (e.g.
^FO) - the 1-based argument number, when argument-specific
- the byte span in the submitted ZPL — pointing at the offending argument itself for argument-level warnings — resolved to line/character positions in the viewers
Related pages
- Linting & Warnings —
how the API delivers these via the
X-Warningsheader, and how the format compares with Labelary's - ZPL Commands Reference — per-command documentation and renderer support status