Troubleshooting

Client shows as Offline

Symptoms: The client appears as "Offline" in Settings → Printers, even though the app is running.

Solutions:

1. Check that the Printer Client app is running (look for it in the system tray)
2. Verify the server URL is correct in the Printer Client settings
3. Check your internet connection
4. Click Reconnect in the Printer Client
5. If the API key was regenerated, update the client with the new key

Printers not showing up

Symptoms: The client is online but no printers are listed.

Solutions:

1. Make sure printers are installed and visible to your operating system
2. Click Refresh in the Printer Client to re-detect printers
3. On macOS/Linux, verify CUPS is running: lpstat -a in the terminal
4. On Windows, check that printers appear in Windows Settings → Printers & Scanners

Print jobs stay as Pending

Symptoms: Jobs are created but never reach the Printer Client.

Solutions:

1. Verify the Printer Client is online and connected
2. Check that the job's target printer client matches the connected client
3. Look at the Printer Client's Logs tab for errors
4. Jobs expire after 2 hours - create a new print job if expired

Labels print at wrong size

Symptoms: Shipping labels are too big, too small, or cut off.

Solutions:

1. Check the paper size in your print defaults (Settings → Printers → Printer Defaults)
2. For shipping labels, use Label 100×150 or Label 100×200
3. If using a custom size, verify the width and height in millimeters
4. Check the printer's own settings - some label printers need media size configured in the driver

Print quality issues

Symptoms: Labels are faded, blurry, or have lines.

Solutions:

1. Check your printer's ribbon/thermal head
2. Clean the print head
3. Adjust print density in the printer's own settings
4. Ensure you're using the correct label media for your printer

API key lost

If you've lost the API key:

1. Go to Settings → Printers in the web app
2. Click Regenerate API Key on the affected client
3. Copy the new key
4. Disconnect the Printer Client and re-enter the new key in setup

Connection keeps dropping

Symptoms: The client frequently reconnects or shows intermittent offline status.

Solutions:

1. Check your network stability
2. The SSE connection times out after 5 minutes by design - the client automatically reconnects
3. If behind a proxy or firewall, ensure SSE/long-polling connections are allowed
4. Check the Printer Client logs for specific error messages