Troubleshooting
Start with the logs (Install › Run as a system service lists where they are per OS), the admin UI's Dashboard (queues, printers, recent jobs) and Dead letters tab, and the Status page.
Common problems#
| Symptom | Check |
|---|---|
| Nothing prints, jobs stay in the queue | The license: without a valid one printing is paused (License). Check the Status page or node dist/cli.js license. |
| Test print or re-send fails with exit code 3 / HTTP 402 | Same: printing is paused until a valid license is installed. |
no printer registered with id |
printers list with the service's home. The job's printer.id must match exactly. |
| CLI changes don't show up in the running daemon | The CLI used a different home: run it as root/Administrator, or with the service's --home (Install › Home directory). |
| Office jobs dead-lettered with "LibreOffice not found" | Install LibreOffice, or set printing.libreOfficePath. |
| Windows PDF jobs fail with "SumatraPDF not found" | Install SumatraPDF, or set printing.sumatraPdfPath. |
| Windows service doesn't see a printer | The service runs as LocalSystem: install the printer machine-wide, not per user. |
| ZPL printer not discovered | Turn SNMP on in the printer, or add it manually (Printers › Manual setup). It may also be listed under Devices that need your decision. |
| Labels print too small or cut off | The printer's resolution setting (Printers › Label resolution). |
| Office layout differs from Word | Install the metric-compatible fonts (Carlito, Caladea, Liberation), or send PDF. |
| Jobs retried forever on SQS | Set a redrive policy (maxReceiveCount) on the queue, and/or deadLetterQueueUrl. |
| Long Office conversions redelivered | Raise visibilityTimeoutSeconds (SQS) or maxAutoLockRenewalDurationMs (Azure). |
| Pub/Sub messages never arrive | Use a Pull subscription, and make sure no proxy downgrades pubsub.googleapis.com to HTTP/1.1 (Queues › Network and firewall). |
| The service stopped after a Node.js upgrade | The service records the path of node: run service install again. |
| A job printed twice | A crash after the printer accepted a job but before its id was saved, or the same dead letter re-sent from the UI and the CLI at once (Queues › Delivery semantics). |
Check the configuration#
bash
node dist/cli.js config validate # checks <home>/config.json
node dist/cli.js config show # the effective configuration, secrets redacted
node dist/cli.js queues list # queues, secrets masked
node dist/cli.js printers listContact#
Email support@insanelab.dev with the version (shown at the top of these pages and on the
Status page), your OS, the queue vendor, and the relevant log lines. Don't send your license key or secrets
from config.json.