> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plato.ae/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose driver, printer, queue, Redis, HTTPS, and Console issues.

# 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:

```sh theme={null}
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:

```sh theme={null}
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 Error                             | Meaning                                | Fix                                                         |
| -------------------------------------- | -------------------------------------- | ----------------------------------------------------------- |
| `Connection Refused`                   | Host is reachable but port is closed.  | Check printer port and raw TCP setting.                     |
| `Connection Timeout`                   | Cannot reach printer IP/port.          | Check IP, network, VLAN, firewall, printer power.           |
| `Printer open timed out after 2000ms`  | TCP connect did not complete.          | Check printer network path.                                 |
| `Printer write timed out after 6000ms` | Socket opened but did not flush write. | Reboot printer, check buffer, network, or printer firmware. |
| `TCP connection closed`                | Printer closed socket unexpectedly.    | Recheck printer raw port and job payload size.              |

## Jobs Stuck

Inspect queues:

```sh theme={null}
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.

## Print Request Accepted But Nothing Prints

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:

```json theme={null}
{
  "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:

```sh theme={null}
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:

```sh theme={null}
curl http://localhost:8080/mesh-status
```

If mesh is disabled, set:

```json theme={null}
{
  "features": {
    "meshEnabled": true
  }
}
```

If HTTPS is used, mesh uses:

```txt theme={null}
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:

```sh theme={null}
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.