Troubleshooting
The label comes out blank
Blank labels have four common causes, and they are quick to tell apart: the format never closed, the media type is wrong, the darkness is too low, or the printer is feeding past your label.
Rule out the file first
Before touching the printer, check whether the format is complete. A printer that receives an ^XA and never receives its ^XZ has not been told to print anything yet — it is holding the label open, waiting for more data. Nothing comes out, and no error is reported, because from the printer's point of view nothing has gone wrong.
^XA
^FO50,50^A0N,40,40^FDShipment 4821^FSThis is the single most common cause when a label stops appearing after a code change, because the usual way to produce it is string concatenation that dropped its last line. It is also the easiest to confirm: paste the file into a validator and it will name the format that never closed.
Then the ribbon question
If the format is complete, the next suspect is the media setting. ^MT chooses between thermal transfer, which needs a ribbon, and direct thermal, which does not — and one of the two mismatches is completely silent.
- Thermal transfer mode with no ribbon loaded: the printer stops and reports a ribbon-out error. Loud, and therefore easy.
- Direct thermal mode with a ribbon loaded: the printhead heats media that is not heat-sensitive, the ribbon sits there unused, and a perfectly blank label comes out. No error, no warning, nothing on the label.
The second one is the blank-label case. If the labels are coming out blank but clean, and the printer is happy, check ^MT against what is actually loaded.
Darkness that is too low to see
Darkness controls how much heat the printhead applies. Set far enough down — or left at a value tuned for different media — the image is technically there and invisible. Hold the label at an angle to the light before deciding it is blank; a very faint print looks blank flat-on.
~SD sets the darkness outright and ^MD nudges whatever the printer already has. If labels went faint after a media change, the media is usually the cause and the darkness is the fix: different stock takes heat differently.
Or the printer is printing somewhere else
The last cause is not really a blank label — it is a label printed on the gap, the liner, or the next label along. That happens when the printer's idea of where a label starts does not match the roll, which is a media-tracking problem rather than a printing one.
The tell is that blanks alternate with prints, or that the image creeps down the roll a little further each time. If that is what you are seeing, the fix is ^MN and a calibration rather than anything in the label.
None of the last three causes is visible in any preview: a renderer has no printhead, no ribbon and no media. A preview tells you the format is right; only a test print tells you the printer is.
Check the label in the validator
The unclosed format above, loaded and ready. The validator reports it with the line and column of the ^XA that was never closed.
Check the label in the validatorCommon questions
- The preview looks correct but the label is blank. What does that tell me?
- That the ZPL is fine and the problem is physical — media type, darkness, or media tracking. A preview draws the format; it cannot see a ribbon or a printhead.
- Why does no error appear when a label prints blank?
- Because from the printer's side nothing failed. Direct thermal mode with a ribbon loaded is a valid configuration, an unclosed format is just a format still being received, and low darkness is a setting. Only ribbon-out in transfer mode raises an error.
- Every other label is blank. Is that the same problem?
- No — alternating blanks are a media-tracking symptom. The printer is finding the top of the label in the wrong place, so one image lands on the label and the next on the gap. Set ^MN for your stock and calibrate.