Launch

30% off your first month of Pro30% off month one$9.90 → $6.93

See plans
ZPL em PDF

Guide · Troubleshooting

Your ZPL label came out wrong: what happened

Nearly every ZPL label problem comes down to a handful of causes, and each has a distinctive symptom. This page runs symptom to cause: what you are looking at on screen or on the stock, what produced it, and what to change. If you have the file to hand, every fix below can be tested in the converter underneath, with no printer involved.

Checked on September 1, 2026

Everything printed on one line, run together

The most common symptom there is, and always the same cause: a missing ^FS. ^FS closes the current field, and without it the next command is read as more of the previous field's data — so three address fields become one long run of text.

Look through your file for an ^FD with no ^FS before the next ^FO. It is nearly always a single field somewhere in the middle, emitted by a system that forgot to close it.

Accented characters come out mangled

“Café” prints as “Café”, or a strange character replaces an umlaut. A ^CI28 is missing from the top of the label — the command that tells the printer to read field data as UTF-8.

Add ^CI28 straight after ^XA and it goes away. If the system generating the file cannot emit UTF-8, the other route is ^FH with the bytes escaped in hexadecimal.

The barcode will not scan

If the barcode looks fine on screen and the scanner refuses it, the prime suspect is not in the ZPL at all: it is the print dialog's “fit to page”. That rescales the label by a few percent, and a few percent is enough to put the bars at the wrong width. Print at 100% scale, every time.

The second cause is ^BY, which sets the module width for every barcode after it; a module too narrow for the printer's resolution produces bars that merge. The third is the payload not matching the symbology — EAN-13 needs exactly 12 digits, Interleaved 2 of 5 needs an even count.

The label is blank, or clipped

A blank label in the converter nearly always means the block draws nothing — ^XA^MCY^XZ, for instance, is printer housekeeping and is dropped on purpose, so a file of fifty labels does not become a hundred pages.

Clipped is a different thing: the file's ^PW or ^LL is smaller than its content, or the density is wrong. With no ^PW and ^LL at all the converter grows the canvas to fit rather than cropping, so a clipped label usually does carry those commands, with values that are too small.

The QR code comes out empty

^BQ does not take its payload directly: the ^FD needs a prefix of its own in front of it. The form is ^FDQA,your-content — where QA selects automatic mode. Pasting a bare URL after ^FD yields an empty QR or a warning.

It is the trap that catches most hand-written QR codes, because every other barcode command takes its payload raw and this one alone does not.

A command shows up as a warning

A warning is not a fault in your file: it means we recognised the command and chose not to draw something that would be wrong. Four symbologies land here (^BK, ^BM, ^BR and ^BZ), and the field is skipped rather than producing a code no scanner would read.

Hardware commands — ^MD for darkness, ^MT for media type, ^PR for speed — are accepted silently and change nothing about the image, because a renderer has no printhead. That is correct behaviour and not a problem with your file. The command reference lists which are which.

Test the fix on your own file, with no printer

Drag the file in, paste the code, or pick it from your device

.txt · .zpl · .prn · .zip · .pdf · .png · .jpg — 30 labels a day

The conversion happens in your browser: your file never leaves your device.How that works
Free, no signupNo uploadNo watermarkBatches of many filesPDF · PNG · ZIP

Questions

Frequently asked questions

Why does my ZPL label print all on one line?

A field is missing its ^FS. ^FS closes the current field, and without it the next command is read as a continuation of the previous field's data, running everything together. Look for an ^FD with no ^FS before the next ^FO.

Why do accented characters print wrong on a thermal label?

^CI28 is missing. It selects UTF-8 for field data; without it the printer falls back to its own default encoding and an accented character arrives as two mangled ones. Add ^CI28 immediately after ^XA.

Why won't my barcode scan after printing?

Most often the label was printed with “fit to page” enabled, which rescales the bars. Print at 100% scale. If it persists, check ^BY: a module width too narrow for the printer's resolution makes the bars merge.

The converter showed a warning. Is my file broken?

No. The warning says we recognised the command and preferred to skip the field rather than draw something incorrect — it happens with four rarely-used symbologies. The rest of the label renders normally, and printer hardware commands are accepted silently on purpose.

Other guides