Basic diagnosis
- 01
1. Print the built-in test
If it fails, the problem is the connection, permission, paper or printer, not yet the integration.
- 02
2. Confirm the destination
Check that the job targets the correct configured printer and that it is on and loaded with paper.
- 03
3. Check permissions
Disconnect and reconnect USB, or check Bluetooth and notification permissions for your Android version.
- 04
4. Send plain text
Remove logos, QR codes, commands and special characters until the basic flow works.
- 05
5. Collect details
Record the model, connection, Android version, app version, failure time and each test result.
Nothing prints or the printer appears disconnected
Network
Check that the IP is reachable from the same network, has not changed, uses the correct port, and is not isolated by a guest network.
USB
Try another cable or OTG adapter, grant permission again, avoid unpowered hubs and check that Android detects the device.
Bluetooth
Remove and pair the printer again in Android, move the devices closer and check that another app is not holding the connection.
The ticket prints, but looks wrong
| Symptom | Check | Action |
|---|---|---|
| Incorrect accents or symbols | Code page test | Select a compatible code page and repeat the actual text |
| Text cut off at the sides | Paper width and font size | Correct the profile, custom width or font-size commands |
| Distorted or cropped logo | Width, greyscale and inversion | Reduce the image and test each option separately |
| Too much paper feed | Lines before cutting and line breaks | Reduce feed and remove unnecessary $intro$ markers |
| Cutter or drawer does not work | Model's ESC/POS capabilities | Test variants and confirm hardware/connector support |
| QR code cannot be scanned | Size, density and content | Shorten the data, change size and avoid blurry printing |
A remote job does not arrive
- Confirm that the built-in test for printer 1 works.
- Check that the web service is enabled and the device remains connected to the Internet.
- Check that the linkcode matches without publishing it in screenshots or logs.
- Disable battery restrictions for the service where device policy permits.
- Check for pending jobs before sending again to avoid duplicate tickets.
- Remember that pn does not select a printer in the reviewed remote backend.
Image and PDF problems
- Check that PosPrinterDriver can access the URL or URI and that read permission remains valid.
- Reduce oversized images before sharing them.
- Avoid transparent backgrounds that could unexpectedly turn black.
- Only the first PDF page is processed; split multi-page documents.
- If a preview appears, confirm the printer and use direct=1 only after testing the flow.