Fixed port?
Shown in client UI; npm auto-connects by default.
WebSocket connection troubleshooting
When the browser cannot reach the local client, check service status, firewall, and extensions—align UX with error handling.
Common symptoms
| Symptom | Likely cause |
|---|---|
| getConnectStatus false | Client not running |
| Timeout | Firewall/AV blocks 127.0.0.1 |
Troubleshooting steps
- Start the desktop client
- Check port in client UI
- Test with firewall/AV disabled briefly
- Try another browser
- Log via getConnectStatus / formatPrintError
Prevention
- Auto-start client on boot for kiosks
- Train users: connect client before print
Read next
FAQ
HTTPS page + ws?
127.0.0.1 ws usually works; check mixed content.
Frontend in Docker?
Client must run on the user PC host.
Remote print WebSocket?
Local client ws + server push channel—remote-print guide.
User-friendly errors?
Use formatPrintError—error-handling guide.
Client deployment by platform
The same web-print-pdf front-end runs on Windows, macOS, and Linux/domestic OS—install the matching client on each desktop.