Troubleshoot printing
Audience: Admin / front desk
Objective: Fix missing or wrong receipts.
Symptoms
- Nothing prints after checkout/sale
- Layout looks wrong on thermal paper
- Raw USB / Bluetooth printer never fires from the browser
- Bluetooth printer is connected in phone Settings but missing from the print dialog
₹garbles on hardware
Likely causes
| Cause | How to check |
|---|---|
| Printing disabled | Settings → Property printing toggles |
| Browser transport only | transport: browser uses OS print dialog — many BLE thermals never appear there |
| Need Bluetooth transport | Set transport to bluetooth, use Chrome/Edge, click Send test receipt |
| Classic BT (SPP) only | Web Bluetooth picker will not list the device — use Download .bin + vendor app |
| Server transport without agent | PRINT_AGENT_URL unset → API may return 501; client falls back to download |
| Wrong paper width | paperWidthMm 58 vs 80 |
| Firmware code page | Entry-level ESC/POS may not render UTF-8 ₹ |
Fix
- Confirm printing enabled and paper width.
- If Bluetooth is paired but not in the OS printer list: choose Bluetooth, save, send test receipt, pick the device in Chrome’s picker.
- For everyday OS printers: browser print.
- For raw thermal without BLE: download
.bin+ vendor utility, or configure a LAN print agent. - Remember: receipts are English only - there is no Hindi bill mode.
Related
- Printing setup
- For engineers:
docs/PRINTING.md