Skip to main content

​
Troubleshooting

Start with the smallest path first:
  1. Driver process health.
  2. Driver-to-printer TCP reachability.
  3. Queue state.
  4. Console printer config.
  5. HTTPS or browser trust issues.

​
Driver Not Reachable

Check: 
curl http://localhost:8080/health
If local health fails:
  • Confirm plato-printer.exe is running.
  • Confirm config.json is valid JSON.
  • Confirm server.port is not already used.
  • Check the startup logs for Port already in use.
If local health passes but POS cannot reach it:
  • Open Windows Firewall for server.port.
  • Use the driver’s network address from the startup banner.
  • Confirm the POS device is on the same network or allowed VLAN.

​
Printer Offline

Call: 
curl -X POST http://localhost:8080/status \
  -H "Content-Type: application/json" \
  -d '{"ip_address":"192.168.1.50","port":"9100","validate":true}'
Common causes:
Last ErrorMeaningFix
Connection RefusedHost is reachable but port is closed.Check printer port and raw TCP setting.
Connection TimeoutCannot reach printer IP/port.Check IP, network, VLAN, firewall, printer power.
Printer open timed out after 2000msTCP connect did not complete.Check printer network path.
Printer write timed out after 6000msSocket opened but did not flush write.Reboot printer, check buffer, network, or printer firmware.
TCP connection closedPrinter closed socket unexpectedly.Recheck printer raw port and job payload size.

​
Jobs Stuck

Inspect queues: 
curl http://localhost:8080/queue-status
Read:
  • waiting: jobs ready but not active.
  • active: currently printing.
  • delayed: future scheduled or retry-delayed jobs.
  • failed: failed jobs retained by BullMQ.
  • totalPending: waiting plus delayed across all printers.
  • isProcessing: at least one active job exists.
If failed jobs are retrying forever, fix the printer connection first. The queue will recover automatically once the printer is reachable. If /print returns { "ok": true, "queued": true }, the driver accepted the job. Next checks:
  1. GET /queue-status.
  2. POST /status with validate: true.
  3. Printer IP and port in Console config.
  4. Printer model supports ESC/POS raster over TCP.
  5. Printer has paper and is not paused.

​
Missing Printer Address

The current driver requires both: 
{
  "ip_address": "192.168.1.50",
  "port": "9100"
}
In Console, this usually means the physical printer IP or port is missing. The driver URL is not the same as the printer IP.

​
HTTPS Fails

Check: 
curl http://localhost:8080/ca.crt
curl https://plato-printer.local/health
Likely fixes:
  • Install the CA certificate on the POS device.
  • Make plato-printer.local resolve to the driver machine.
  • Open port 443.
  • Confirm assets/certs exists.
  • Confirm Caddy started in logs.

​
Mesh Fails

Check: 
curl http://localhost:8080/mesh-status
If mesh is disabled, set: 
{
  "features": {
    "meshEnabled": true
  }
}
If HTTPS is used, mesh uses: 
wss://plato-printer.local/mesh

​
Redis Fails To Start

Embedded Redis startup can fail if:
  • The configured Redis binary version is missing or corrupted.
  • The configured Redis port is already in use.
  • Windows blocks the downloaded binary.
  • The detected Redis version does not match redis.version.
Fixes:
  • Run the bundle script to prepare redis-binaries.
  • Change redis.port.
  • Delete the bad redis-binaries/<version> folder and rebuild.
  • Use redis.mode: "external" with a known-good Redis server.

​
Safe Reset

For a local reset during development: 
pnpm --filter @plato/pc-printer clean
This removes dist, output, logs, plato-printer.zip, and dump.rdb. In production, do not delete dump.rdb unless you intentionally want to clear persisted queues and known printer registry state.