​

Troubleshooting

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

curl http://localhost:8080/health

• 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.

• 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

curl -X POST http://localhost:8080/status \
  -H "Content-Type: application/json" \
  -d '{"ip_address":"192.168.1.50","port":"9100","validate":true}'

​

Jobs Stuck

curl http://localhost:8080/queue-status

• 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.

​

Print Request Accepted But Nothing Prints

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

{
  "ip_address": "192.168.1.50",
  "port": "9100"
}

​

HTTPS Fails

curl http://localhost:8080/ca.crt
curl https://plato-printer.local/health

• 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

curl http://localhost:8080/mesh-status

{
  "features": {
    "meshEnabled": true
  }
}

wss://plato-printer.local/mesh

​

Redis Fails To Start

• 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.

• 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

pnpm --filter @plato/pc-printer clean