Home›Guides›Previewing and debugging TSPL without a printer
Previewing and debugging TSPL without a printer
Published:
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
Confirm the language. TSPL, EPL and CPCL files all look "not like ZPL"
at a glance; the language
detector settles it from the code.
Render it. If the image is empty, check CLS,
PRINT and whether any content command was skipped.
Read the findings top to bottom — a field-count error early in the job
often explains everything after it.
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.
