Troubleshooting

This page covers common issues encountered with the POS Terminal and their solutions. If your issue is not listed here, contact your system administrator or check the application logs at logs/pos-terminal.log.

Printer Not Responding

Symptoms: Receipts do not print after completing a sale, or the printer light is off.

Solutions:

1. Check that the printer is powered on and the USB or network cable is securely connected.
2. For USB printers, verify the printer appears in the system's device list. On Linux, run lsusb and look for the printer manufacturer.
3. For network printers, confirm the printer's IP address is reachable by running ping <printer-ip> from the store terminal.
4. Restart the POS Terminal application. The printer connection is re-established on startup.
5. Check the printer has paper and is not showing an error light (usually a flashing red LED indicates a paper jam or cover open).

If receipts still do not print, the sale is not lost. All transactions are stored in the database regardless of printer status. You can reprint any receipt from the transaction history.

Barcode Scanner Not Detected

Symptoms: Scanning a barcode does nothing on the POS Terminal screen.

Solutions:

1. Unplug the scanner and plug it back in. Most USB scanners are automatically detected.
2. Ensure the scanner is configured to operate in keyboard emulation mode (HID). Most scanners ship in this mode by default, but check the scanner manual if it was recently reset.
3. Make sure the POS Terminal input field is focused. Click on the main sale screen if another dialog has taken focus.
4. Test the scanner with a text editor. If the barcode data appears in the editor but not in the POS Terminal, the issue is in the application configuration rather than the hardware.

Sync Failures

Symptoms: The sync status indicator shows "Offline" or "Error" even though the store has internet connectivity.

Solutions:

1. Verify the HQ server is running and accessible. Try reaching the HQ sync endpoint from the store machine: curl https://hq.example.com:3001/health.
2. Check the SYNC_TOKEN in the store server .env file. If the token was revoked or expired, generate a new one from HQ Manager.
3. Review the store server logs for specific error messages. Common causes include expired TLS certificates, firewall rules blocking the WebSocket port, or DNS resolution failures.
4. Restart the store server. The sync connection will be re-established automatically.

Sales and other local operations are unaffected by sync failures. All data is stored locally and will sync once the connection is restored.

Register Stuck Open

Symptoms: A cashier cannot open a new register session because the system reports the register is already open, but no one is using it.

Solutions:

1. This usually happens after a crash or power outage during an active session.
2. A user with the pos:force_close_register permission (typically a store manager) can force-close the stale session from Menu > Manager > Force Close Register.
3. Force-closing creates a Z Report with the available data. The cash count is recorded as zero since no physical count was performed.
4. After force-closing, the register is available for a new session.

Slow Product Search

Symptoms: Typing in the product search field has a noticeable delay before results appear.

Solutions:

1. The local product database may need reindexing. Restart the store server, which triggers a reindex on startup.
2. If the store has a very large product catalog (over 50,000 items), consider upgrading the store machine's memory or storage to an SSD if it is currently using a mechanical hard drive.
3. Check that PostgreSQL is running and responsive with docker compose ps or your process manager.