SDB:How to Report a Printing Issue
tagline: From openSUSE
|Tested on openSUSE||Recommended articles||Related articles|
- 1 Situation
- 2 Basics
- 3 Details
- 3.1 Always tell the openSUSE version
- 3.2 Always tell the exact printer model name
- 3.3 Always tell how the printer is connected
- 3.4 Always tell which printer driver is used
- 3.5 Always tell exactly what you did
- 3.6 If applicable provide an example file
- 3.7 Usually provide CUPS debug messages
- 3.8 Do not overdo things
- 4 Background Information
- 5 See also
You have a printing issue and like to ask for help or report a bug but you do not know which information you must provide so that others can help you or understand your bug report.
See Concepts printing for information about printing basics.
Do not assume someone knows about your particular environment and what you did.
In any case provide sufficient information about your particular environment and what you did and usually provide CUPS debug messages.
On the other hand do not overdo things by flooding the audience with tons of information that was not requested.
In general regarding "How to Report Bugs Effectively" it is recommended to have a look at http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
Always tell the openSUSE version
Even if you are 100% sure that all others use the same openSUSE version as you currently do, tell which openSUSE version you use and how you installed it.
Was it an update of an existing older openSUSE version (if yes, which exact older version) or did you install your current openSUSE version from scratch?
Do you use only software packages from openSUSE or do you also use other software like newer versions of particular packages or self-compiled software which might be related to your printing issue?
If you use other software which might be related to your printing issue, tell which exact other software it is and provide an URL wherefrom you got the other software.
Always tell the exact printer model name
Do not assume the printer model is irrelevant.
Even if you are 100% sure that your particular issue cannot depend on your particular printer model, tell the model nevertheless.
Provide the exact model name as labeled on the printer device. For example when the device is labeled "ACME FunPrinter 1000 XL+" then provide its full name and not any kind of abbreviation like "ACME 1000 XL" because there could be a different model "ACME FancyPrinter 1000 XL" and even tiny details like the '+' could make a difference which driver works for the particular model.
Always tell how the printer is connected
Do not assume it is irrelevant how your printer is connected to the Linux system from where you submit the print job.
What does the YaST "Add New Printer Configuration" or "Modify" dialog (see YaST Printer) or whatever setup tool show as connection?
Or more precisely: What is the CUPS device URI on the Linux system from where you submit the print job? I.e. what is the output of the command
lpstat -v <queue_name>
provided you have already set up your printer (replace <queue_name> with your print queue name). If printer setup failed, provide the output of the command (run it as root)
and see below.
Always tell which printer driver is used
Do not assume it is irrelevant which exact driver you use for your particular printer model.
What does the YaST "Add New Printer Configuration" or "Modify" dialog (see YaST Printer) or whatever setup tool show as driver?
Or more precisely: What are the NickName and cupsFilter entries in the PPD in /etc/cups/ppd/<queue_name>.ppd (replace <queue_name> with your print queue name)? I.e. what is the output of the command
egrep 'NickName|cupsFilter' /etc/cups/ppd/<queue_name>.ppd
provided you have already set up your printer. If printer setup failed, see below.
Do you use the driver from the openSUSE printer driver software packages (see Concepts printing) or do you use other driver software like drivers from the printer manufacturer?
If you use other driver software, provide an URL wherefrom you got the other driver software.
Always tell exactly what you did
Do not assume others know what you did.
Even if you are 100% sure that your particular way how you do it is the same as all others do, tell exactly what you did nevertheless.
If printer setup fails
Which printer setup tool are you using?
We have many printer setup tools which could be launched via various ways depending on which desktop is currently used:
- YaST printer setup tool (see YaST Printer)
- Gnome printer setup tool ("system-config-printer")
- KDE printer setup tool
- CUPS web frontend (see SDB:CUPS in a Nutshell)
- CUPS command line tools ("lpinfo"/"lpadmin", see SDB:CUPS in a Nutshell)
- for HP devices: HP's setup tool "hp-setup" (see SDB:How to set-up a HP printer)
- anything else (e.g. a setup tool from a printer manufacturer)
If you don't know which printer setup tool the desktop magic runs, provide a screenshot or try if there is a "help" or "about" info in your printer setup tool.
Tell exactly step by step what you did in the printer setup tool and what the printer setup tool shows to you in each step (in particular exact error messages).
If printing from an application program fails
Does printing a test page from a printer setup tool work?
YaST provides a "Print Test Page" button in its initial "Printer Configurations" dialog.
Does printing from the command line work?
Does printing work when you run the following commands? Replace <queue_name> with your print queue name and use the command that matches the media (A4 or Letter) that is actually loaded in your printer:
echo Hello | lp -d <queue_name>
echo A4 | a2ps -1 -M A4 -o- | lp -d <queue_name> echo Letter | a2ps -1 -M Letter -o- | lp -d <queue_name>
echo -e 'One\fTwo' | lp -d <queue_name>
echo -e 'A4-1\fA4-2' | a2ps -1 -M A4 -o- | lp -d <queue_name> echo -e 'Letter-1\fLetter-2' | a2ps -1 -M Letter -o- | lp -d <queue_name>
You should get:
- one page with "Hello"
- one page with "A4" or "Letter"
- two pages with "One" and "Two"
- two pages with "A4-1" and "A4-2" or "Letter-1" and "Letter-2"
If the output of the commands for "A4" or "Letter" does not fit on your paper, try out the following commands:
echo A4 | a2ps -1 -M A4 -o- | lp -d <queue_name> -o PageSize=A4 echo Letter | a2ps -1 -M Letter -o- | lp -d <queue_name> -o PageSize=Letter
If one of those comands works, you need to adjust the default paper size of your print queue and also in your application program to match what is actually loaded in your printer.
To adjust the default paper size of a print queue run as root one of those commands:
lpadmin -p <queue_name> -o PageSize=A4 lpadmin -p <queue_name> -o PageSize=Letter
It depends on the particular application program how to adjust its paper size to match what is actually loaded in the printer.
Does printing from other application programs work?
Does printing work when you run the same application program under a different user account?
You may set up a new test-user and try to print as the test-user. Different users could obtain different printout results, even though they print identical data via the same print queue, see SDB:Print Settings with CUPS.
Which application program are you using where printing fails?
If you don't know which application program the desktop magic runs, provide a screenshot or try if there is a "help" or "about" info in your application program.
If printing from an application program fails, provide sufficient information so that others have a chance to reproduce the failure.
In particular tell when you changed any of the default settings in the print dialog of the application program e.g. "landscape" printing (see SDB:Landscape Printing) or a high resolution like "1200x1200dpi" (see SDB:Laser Printer Does Not Print Properly Or Does Not Print At All).
If printing from command line fails
Provide the exact printing command and a small example file (when you print a file) where printing fails for you.
If applicable provide an example file
If printing from an application program fails, provide an example file that fails for you (or a reference to a public accessible example file) and provide what the application submits as printing data to CUPS in your particular case.
For example when printing from a browser fails, provide an URL to a commonly known and public accessible web page (e.g. an openSUSE web page) where the printout of this web page fails in the particular browser.
When the application program works with files (for example a PDF reader or an office software like LibreOffice/OpenOffice), provide a small example file where the printout of this example file fails in the particular application program. For example a small PDF file for a PDF reader or a small LibreOffice/OpenOffice document when printing from LibreOffice/OpenOffice fails.
Do not provide big example files like PDFs or office documents with many pages. Even if the failure happens for you on page 123 of a 234 pages document, do not provide the whole document. Instead try to extract only the part of the document which causes the failure (e.g. only page 122 up to 124) and provide this as small example document - provided it still fails for you with your example document.
If printing from an application program fails, provide additionally what the application submits as printing data to CUPS when printing the above example file that fails to print for the particular application program. A precondition is that printing from an application program does not already fail in the application itself when it makes its printing data before it gets submitted to CUPS.
To get what the application submits to CUPS do the following:
- Stop printing for your print queue. As user 'root' run "cupsdisable <queue_name>" (replace <queue_name> with your print queue name).
- Clean up all your print queues. As user 'root' run "cancel -a" which completely removes all existing (old) print jobs (including job history) in all print queues.
- As normal user print the exact example file where printing fails from the particular application program.
- What the application had submitted in the previous step to CUPS is now hold in the print queue as /var/spool/cups/d<job_number>-001 (see "Saving the print job in the spool directory" in SDB:CUPS in a Nutshell).
- Save the print job data for further analysis. As user 'root' run "cp /var/spool/cups/d<job_number>-001 /tmp/print-job-data.save" (replace <job_number> with your actual print job number) and "chmod a+r /tmp/print-job-data.save" to make it accessible also as normal user for later analysis (see below).
- Clean up the print queue. As user 'root' run "cancel -a <queue_name>" (replace <queue_name> with your print queue name).
- Re-enable printing for your print queue. As user 'root' run "cupsenable <queue_name>" (replace <queue_name> with your print queue name).
- Now /tmp/print-job-data.save can be inspected at your leisure.
If printing from an application program fails, the first test is to check if what the application had submitted as printing data to CUPS seems to be correct.
Usually application programs submit either PostScript or PDF as printing data format to CUPS (see "common printing format" at Concepts printing).
To test if the PostScript or PDF that an application had submitted to CUPS seems to be correct, get it as described above and then display it with Ghostscript:
gs -r50 /tmp/print-job-data.save
This opens a X11-window that shows the graphical content of a PostScript or PDF page. At the command line where you typed the "gs" command, press the [Enter/Return] key to show the next page. To exit Ghostscript type "quit" or press the [Ctrl/Strg]+[C] keys.
Possible errors are shown at the command line where you typed the "gs" command. In case of errors, the application had submitted invalid PostScript or PDF to CUPS. To only test if the PostScript or PDF is valid run "gs -r50 -dNOPAUSE -dBATCH /tmp/print-job-data.save" to let Ghostscript show the pages continuously. If there are no errors, it only means that Ghostscript does not fail to process it. When you have a PostScript printer the printer might fail to print it nevertheless (see Concepts printing).
If there are no errors, check if the graphical content is what you expect. The "-r" parameter specifies the resolution so that "-r100" shows the graphical content at double size compared to "-r50". The graphical content that is shown by Ghostscript is what the application had submitted and what your printer should print.
Usually provide CUPS debug messages
In almost all cases when printing does not work you should provide CUPS debug messages:
- In /etc/cups/cupsd.conf set "LogLevel debug". As user 'root' set the "LogLevel" value to "debug" in /etc/cups/cupsd.conf using a plain text editor like 'vi' or 'nano', see Text editor.
- Stop cupsd. As user 'root' run "rccups stop" or in case of systemd use appropriate systemctl commands like "systemctl stop cups.service" and so on (check the output of "systemctl list-units | grep cups" and "systemctl list-unit-files | grep cups").
- Move /var/log/cups/error_log to another location (or delete it) in order to avoid having to search through gigantic log files. As user 'root' run "mv /var/log/cups/error_log /var/log/cups/error_log.old" (or "rm /var/log/cups/error_log").
- Start cupsd. As user 'root' run "rccups start" or in case of systemd use appropriate systemctl commands like "systemctl start cups.service" and so on.
- Retry the action leading to the problem.
- Now /var/log/cups/error_log contains many messages that are useful for troubleshooting.
- Save the current /var/log/cups/error_log for further analysis. As user 'root' run "cp /var/log/cups/error_log /tmp/cups.error_log.save".
- Now /tmp/cups.error_log.save can be inspected for interesting messages at your leisure.
Provide CUPS debug messages only for one single failed print job. Do not provide a whole /var/log/cups/error_log file, except its content belongs only to one single failed print job.
Some printer drivers may pollute the /var/log/cups/error_log file with zillions of driver internal debug messages which are usually meaningless to find out why a print job failed. In such cases only provide those CUPS debug messages which seem to be of real interest regarding the failure of the print job. Look for "error" or "fail" messages and include several lines before the "error" or "fail" message appears in your printing issue report. Try to imagine which of the lines before the "error" or "fail" message could to be of real interest regarding the failure of the print job.
There are a few examples where CUPS debug messages won't help:
When printer setup fails (i.e. it fails to set up a print queue), then CUPS debug messages won't help because without a print queue no print job can be processed by CUPS (see Concepts printing).
If printing from an application program fails in the application itself when it makes its printing data before it gets submitted to CUPS, there is no print job that can be processed by CUPS (see Concepts printing).
When printing basically works (i.e. you get a printout) but there are differences in size or position of the printout on the paper or there is a color cast or there are visual artifacts (see SDB:Purchasing a Printer and Compatibility), then CUPS debug messages won't help because there is no failure of the print job.
When you like to print via a remote CUPS server in the network but this fails, the CUPS debug messages on the remote CUPS server are needed. But when you cannot get them (e.g. because it is a company CUPS server where you do not have access), the CUPS debug messages on your client host from where you submit the print job usually won't help. Nevertheless inspect the CUPS debug messages on your client host to verify that it does not fail on your client host. Furthermore see SDB:Printing via TCP/IP network.
Do not overdo things
Initially you should only provide the above described information.
Do not overdo things by providing tons of low-level debug information that was not requested.
In particular low-level debug messages like "strace" output, backtraces (in particular backtraces without debug info) or even core dumps are usually not really helpful to debug printing-related issues - except you are a sufficient expert to know for which process which particular kind of low-level debug messages is needed and which lines in such an output actually show the root cause of the failure (see openSUSE:Bugreport application crashed).
Also a whole "dmesg" output or even the whole /var/log/messages file is never ever needed to find out the root cause of a printing-related issue.
On the other hand there are printing-related issues where it helps to inspect "dmesg" and /var/log/messages for information which could be of interest regarding the printing-related issue. Such issues are in particular when a locally connected printer is not accessible (see SDB:Installing a Printer). In such cases only provide those messages which seem to be of real interest regarding the printing-related issue. For example if an USB printer is not accessible, you could get usb-related kernel messages via the command:
dmesg | grep -i usb >/tmp/dmesg.usb
Then you can inspect /tmp/dmesg.usb and extract only those messages which seem to be of particular interest regarding the USB printer issue.
Printing is relatively simple from a conceptual point of view: "Just" convert PostScript or PDF into printer-specific data and send that to the printer device (see Concepts printing). But it becomes complicated when you look at a real particular case.
There is no such thing as THE way how to convert PostScript or PDF into printer-specific data.
There are many different ways how an application can make PostScript or PDF, leading to many different ways how PostScript and PDF processing tools (Ghostscript and Poppler/Xpdf) interpret it, together with many different printer drivers where each driver has several driver-specific option settings.
When printing text it depends additionally on the installed font packages which fonts are used by a particular application to make the PostScript or PDF. Furthermore it depends on which software is used for font rendering, for example Ghostscript's font rendering versus FreeType font rendering (see https://bugzilla.novell.com/show_bug.cgi?id=692356).
Furthermore for color printing it depends on the color models that are used in the PostScript or PDF (RGB or CMYK) and by the printer (e.g. CMY, CMYK, CcMmYK, CcMmYy, CcMmYyK).
All together lead to a zillion of ways how printer-specific data can be made for a particular printer with particular driver settings in a particular environment.
Therefore do not assume that something which fails for you also fails for others or that it must have been already detected by those who do beta-testing for openSUSE. Even when it is already a known issue, do not assume that the root cause is "obvious" and an "obvious solution" exists which is correct for all users in any environment.
If you depend on a particular printing functionality in openSUSE, it is you who must test this particular functionality for openSUSE, provide meaningful bug reports, answer questions, and so on.
Be prepared that you may have to report issues which are not caused by openSUSE directly at the matching upstream project. In this case bug reports submitted to openSUSE will get closed as "UPSTREAM", see http://en.wikipedia.org/wiki/Upstream_%28software_development%29 that reads:
Responsibility for a bug is said to lie upstream when it is not caused through the distribution's porting and integration efforts.
In particular when a printing issue depends on the printer model (e.g. a driver does not work or results bad printout quality for a particular printer model), we (i.e. openSUSE) usually do not have such a printer model to reproduce it so that there is basically nothing what we could do in such cases. In contrast when you report the issue directly at the matching upstream project, there is a direct communication between you and the upstream authors.
There is a longer beta-testing phase (a.k.a. "milestones") for each openSUSE release where interested users can test it (see openSUSE:Testing).
"How to Report Bugs Effectively" at http://www.chiark.greenend.org.uk/~sgtatham/bugs.html