CUPS – How to Debug Scanning Issues

If you don’t see your scanner in scanning application, then debugging of discovery process is in order. I prefer using scanimage in the examples, but the similar steps can be applied for every scanning application like xsane, scanadf, simple-scan etc.

You will need to use environment variables when you start a scanning application (scanimage in this case). The environment variables used with scanimage command depends on how your scanner is connected and which backend suppose to support it. So for getting debug logs for HP LaserJet device, connected via Ethernet/Wifi and supported by HPAIO backend, use command:

or, f.e. if you have CanoScan 8600F, connected by USB and supported by genesys backend, use command:

Please attach the created discovery_output file as an attachment to the bugzilla ticket.

If the scanner is found, but an issue happens during scanning itself, we need to debug scanning process itself - which means debugging communication between backend and scanner when you start scanning a document.

The debugging scanning itself looks similar as discovery - setup the environment variables before running the command/scanning application and catch logs into a file. The possible command can be (f.e. if you have network scanner supported by HPAIO backend):

or (once you find out device uri from scanimage -L - see the next section):

, where you substitute <device_uri> for the actual device uri, f.e. 'hpaio:/net/laserjet_m1536dnf_mfp?ip=192.168.1.112'.

Please attach the created file - debug_log - as an attachment to the bugzilla ticket.

This point is basically a manual how to get a scanner uri for debugging scanning itself via scanimage. You don’t need to provide a scanner uri in GUI applications like xsane or simple-scan, because the application will do it for you or you can choose the scanner by a mouse click.

The scanimage -L command returns an output where device uri of the device is shown, f.e.:

F.e.the string 'hpaio:/net/laserjet_m1536dnf_mfp?ip=192.168.1.112&queue=false' is a device uri for for Hewlett-Packard laserjet_m1536dnf_mfp all-in-one scanner.

The hplip package doesn’t have unified logging, so some logs come out of HPAIO backend to standard output and HP internal utilities logs come to journal. So we need to capture both to get the understanding of situation.

It can be done this way:

then attach the created file - journal_logs - as an attachment to the bugzilla ticket. Please do only one action per capture - that means if you are asked to attach log files for HP scanner discovery and scanning supported by hplip, you will attach as an attachment four files - discovery_output, journal_logs for discovery output, debug_logs and journal_logs for debug_logs.

If your device supports eSCL or WSD (you can find it out from device specification - look for the mentioned protocols or AirScan), then its scanning functionality is supported by sane-airscan. Regarding debugging, on the top of usual logging sane-airscan gathers a communication dump and output image, which is helpful during investigation.

sane-airscan debugging can be enabled in /etc/sane.d/airscan.conf by setting:

Then do trigger your issue (discovery or scanning), go to the dir you defined in /etc/sane.d/airscan.conf, take all files from there and attach them to the bug ticket.

In case your debug log is too big for bugzilla to attach (because your issue doesn’t happen with the lowest settings or logs are big even with the lowest settings), do divide the logs to three files like this:

<backend> is the name of backend which supports your scanner (pixma, genesys, plustek, hpaio, airscan etc.), <connection> is the type of connection you use for the device (tcp, usb).

The division makes the investigation more difficult (the person needs to have three opened files at the same time), so do divide the logs only if log file is too big.