Previewing and debugging TSPL without a printer

Published: 2026-08-27

TSPL jobs fail the same way ZPL jobs do — silently. The printer accepts the file, feeds a label, and something is missing or in the wrong place. Reading the job on screen first turns a strip of wasted labels into one browser tab.

A minimal TSPL job, and what each line is for

SIZE 100 mm, 150 mm
GAP 3 mm, 0 mm
CLS
TEXT 100, 100, "3", 0, 1, 1, "HELLO"
BARCODE 100, 200, "128", 100, 1, 0, 3, 3, "123456"
PRINT 1

SIZE declares the physical label in real units — millimetres here, or inches when the unit is omitted. GAP describes the space between labels so the printer knows where one ends. CLS clears the image buffer; without it, the previous job's content can print again. Content commands then draw into that buffer, and PRINT commits it. A missing CLS or PRINT is one of the most common reasons "nothing happened".

What the diagnostics actually tell you

Validation reads the job and reports findings with positions rather than a single pass/fail. The categories you will meet most:

• Unknown command — the line is not TSPL at all, usually a typo or a stray line from another language.
• Wrong field count — TEXT, BARCODE and friends take a fixed number of comma-separated arguments; a missing one shifts every following argument into the wrong slot, so the command is skipped rather than drawn wrongly.
• Barcode type outside the supported set — the preview covers Code 128, Code 39, EAN-13 and UPC-A; other symbologies are reported instead of being faked.
• Invalid rotation — TSPL accepts 0, 90, 180 and 270; anything else is a typo that would silently change the layout.
• Empty barcode data — an empty string produces no symbol; on paper that reads as "the barcode did not print".
• Printer-behaviour command — informational, see below.

Commands a preview will not draw (on purpose)

DIRECTION, OFFSET, BLINE, DENSITY, SPEED, SET and CODEPAGE are recognised and reported, but they are not drawn. They change how the mechanism behaves — feed direction, top-of-form offset, black-mark tracking, burn darkness, print speed, code page — and a screen render cannot honestly reproduce that. Seeing them listed as printer-behaviour findings means the preview is correct and the remaining question belongs to the hardware.

The practical consequence: if your on-screen label is right but the printed one is rotated or offset, look at DIRECTION and OFFSET before you touch the layout.

A debugging order that works

1. Confirm the language. TSPL, EPL and CPCL files all look "not like ZPL" at a glance; the language detector settles it from the code.
2. Render it. If the image is empty, check CLS, PRINT and whether any content command was skipped.
3. Read the findings top to bottom — a field-count error early in the job often explains everything after it.
4. Only then change printer settings, and change one at a time.

Both steps live here: the TSPL viewer renders the job and the TSPL validator lists the findings. The command reference shows every command the engine understands, with its coverage level.

Frequently asked questions

Can I preview a TSPL label without a TSC printer?

Yes. A browser renderer draws the same content commands a printer would — SIZE, GAP, CLS, TEXT, BARCODE, QRCODE, BOX, BAR, REFERENCE and PRINT — and reports findings with positions instead of a single pass or fail.

Why does my TSPL job print nothing?

Most often a missing CLS or PRINT. CLS clears the image buffer and PRINT commits it; without PRINT the printer never outputs, and without CLS the previous job's content can come back. A field-count error early in the job also skips every command that follows it.

Related guides

Try your own ZPL code →