Diagnostics Reference
Every diagnostic code the ZPL engine can report, with severities, examples, and where each appears
The renderer reports the commands it ignores, the defaults it uses, and the output it cannot render as diagnostics. Diagnostics do not change the render.
Where diagnostics appear
| Place | How you get them |
|---|---|
| API (the Labelary-compatible layer) | X-Warnings response header when the request sends X-Linter: On (limited to 20) |
| Online viewer | Inline panel below the preview, plus editor squiggles; repeated warnings across a multi-label file read as one line |
| Desktop app | The same shared panel and squiggles |
Severities
| Severity | Meaning |
|---|---|
info | Normal behavior, such as an explicitly omitted argument slot that uses a default |
warning | The render succeeds, but possibly not as intended (ignored command, trimmed value, default) |
error | The renderer cannot render a barcode or a graphic |
info-level diagnostics appear in the viewers, and never in the API's
X-Warnings header.
Codes
Codes are a stable contract: new codes can appear, and an existing code never changes name.
| Code | Default severity | Reported 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 "^PM" is valid ZPL but is not supported by this renderer yet; it was skipped |
IGNORED_COMMAND | info | Documented ZPL that cannot affect a rendered label | command "^KL" is recognised and intentionally ignored; it configures the printer or reports its state and cannot affect the rendered label |
ARGUMENT_MISSING | info | An argument slot is explicitly omitted (10,,30) | argument 2 of ^FO omitted; default used |
ARGUMENT_TRIMMED | warning | The renderer trims trailing garbage | Value '10abc' is not a valid number; suffix 'abc' was ignored |
ARGUMENT_INVALID | warning | An argument is invalid; the renderer defaults | Value 'ab' is not a valid number and was ignored |
ARGUMENT_OUT_OF_RANGE | warning | An argument is outside its valid range | Value 0 is less than minimum value 1; used 1 instead |
RENDER_ERROR | error | A barcode or a graphic fails to render | failed to render Code 128 barcode (^BC): ... |
RESOURCE_MISSING | warning | The label references a stored object that is absent | ^XG references image "R:LOGO.GRF" which was never stored (no matching ~DG); field skipped |
UNSUPPORTED_COMMAND vs IGNORED_COMMAND
Both codes describe a command the renderer recognizes and does not act on.
UNSUPPORTED_COMMAND | IGNORED_COMMAND | |
|---|---|---|
| Severity | warning | info |
| What it means | The command changes the label if the renderer implements it. It is a gap. | The command cannot change any label. It configures a printer, queries a host, calibrates a sensor, or writes an RFID tag. |
| Does implementation help | Yes, the output differs | No, the output already matches a printer |
In X-Warnings | Yes | No, it excludes info |
| Labelary's behavior | Also does not render it, in almost every case | Also ignores it, silently |
| Published status | planned or unsupported in the support matrix | ignored in the support matrix |
A stream of IGNORED_COMMAND diagnostics does not signal a problem.
UNSUPPORTED_COMMAND does.
The skip policy page lists every ignored command and the reason per family.
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:
; used 10 insteadwhen the renderer clamps the value,and was used as writtenwhen it keeps the value. - Idiomatic trailing omissions (
^FO10,20with no third argument) stay silent. That is normal ZPL, not a mistake.
Source positions
Each diagnostic points at its source as a chain — command, then argument, then message:
- the command as written, with its prefix (e.g.
^FO) - the 1-based argument number, when argument-specific. It counts the
comma-separated slots, and equals the header's
paramNumber - the argument's name, where a number alone would misname it.
^Awrites font and orientation in one slot, so^A0,260,350reportsorientation of ^A omitted; default used, not argument 1, where the font is present - the byte span in the submitted ZPL, covering the offending argument; the viewers resolve it to line and character positions. The header and the viewers use one resolver, so they always agree
Related pages
- Linting & Warnings —
the
X-Warningsheader format, next to Labelary's - Skip Policy — which commands the renderer ignores, and why
- ZPL Commands Reference — per-command documentation and renderer support status