(VII.) Troubleshooting-CUPS-and-Asking-for-Help HOWTO (A Guide For The Desperate)

by Kurt Pfeifle, Danka Deutschland GmbH


Printing is one of the most complicated things in day to day IT usage. CUPS makes printing more easy than ever before. But CUPS is new. It is different in many ways compared to other printing systems. So even experienced administrators sometimes get trapped if they try it for the first time. So don't be shy to ask. But remember: your chances to get a precise and helpful answer depend on asking a precise question and supplying helpful facts. If you don't know which are the helpful facts, this little article is for you. There are quite a few of volunteers trying to help you through any thicket you might have to pass on your way in these CUPS newsgroups (or if you are new to Linux altogether). But we don't want to waste our time on people who don't show an effort themselves.

As the support service through this newsgroup is done by people in their spare time, you should not give the impression of wanting everything fed by the spoon. Just make an effort yourself. If you tell us, what you did so far to solve your problem (and what results that gave), we might not only be much more responsive, but also more able to point you to the right direction.

Read the CUPS documentation!

If you have CUPS installed on your system, and if your CUPS daemon is running, it is available online (HTML and PDF formats) on your local system at http://localhost:631/documentation.html. If the CUPS daemon is not running, you might find it in your file system; the standard location is at /usr/share/doc/cups/. On the CUPS homepage you meet it at http://www.cups.org/documentation.html. Read at least the Software Administrators Manual and the Software Users Manual.

Read the Manual Pages!

Did you make sure you checked the CUPS man pages ?

The most important ones are those for lpadmin, lpr, lp, lpc, lpq, lpstat, cupsd.conf, lprm . At the end of most man pages you might be pointed to other man pages. Go read them too. Check if there are new ones in a new CUPS version by entering apropos cups.

Supply the basic useful facts about your printing environment!

Which operating system? Which version? Which Kernel?

Example: "SuSE Linux 6.4, running Kernel 2.2.18"

Which version of CUPS? Was it the one bundled to your Linux distribution? Did you compile it yourself?

Example: "CUPS 4.1.6...", (hint: you should upgrade to the latest version, currently at least 1.1.14), "...downloaded from www.cups.org as a portable binary and installed through the companion cups.install script".

Supply the facts about you printer installation!

What method did you use to install your printer?

Examples: the CUPS web interface -- the lpadmin command -- or a third party GUI tool, like the KDE Print Manager...

What was the exact command you gave to install it?

Example: lpadmin -p 1st-printer -v socket:// -L "Next to my desk" (Won't work: you used a dash in the printer name and it doesn't start with a character, which at present is "illegal" with CUPS; your socket device URL will most likely not work if you don't give a Port number; you forgot the "-E" parameter to enable the printer; you didn't supply a PPD...)

"My installation went fine, printer is visible, but I've no output..."

So what PPD did you use for your printer? What sort of printer is it? Don't just tell the model name (some people might not know it -- but still *do* tell it), look up in your printer manual (you have one, haven't you?!), which printing languages the device is supposed to support (PostScript Level 2, PCL 5e, ESC/P...) and tell us...

Every printer in CUPS (if it is not used as a "raw" printer) needs a so called PPD (PostScript Printer Description) file. (In CUPS, even non PostScript printers use PPD files). The PPD contains descriptions about every one of the printer's capabilities and the printer specific commands to be send if one or more of those capabilities are to be called for in the print job (f.e. duplex printing from paper tray 3). For non-PostScript printers the PPD also contains a call for the appropriate CUPS- or Third-Party-Filter to be used. (A filter may be only one element in a whole filter chain). The final filter takes a PostScript (or other legal input) file and converts it to the correct raster or other format for the target print device.

PPDs for CUPS are supplied also from third parties, so there is no shortage of them. Unfortunately, there are some very outdated and badly working packages in circulation on the Net and amongst distributions. Make sure you don't use a wrong PPD for your printer.

PPDs installed alongside your CUPS installation:

Those are generic PPDs for 9-pin and 24-pin Epson matrix printers, for Epson Stylus Color and Stylus Photo printers, HP LaserJet and DeskJet printers and Dymo Label printers. These will enable you to print to several hundred different printer models, but will not give you access to specific capacities of the models (duplex, input tray selection, smaller margins,...)

PPDs from a Printer Manufacturer:

Those are distributed alongside a PostScript capable printer. Originally they were intended for MacOS or MS Windows platforms only. CUPS can use them without a change. Normally, the Windows NT versions work flawlessly with CUPS. You get them from the manufacturer's website or from any MS Windows PC that has the PostScript driver for this printer installed. Put a copy into your /usr/share/cups/model/ directory to make it available for installation through the web interface.

PPDs from Easy Software Products:

Those are commercially sold and supported drivers that are supplied (and only work for) ESP PrintPro, the professional printing software made by the creators of CUPS and based on CUPS. ESP PrintPro is available for Linux, Sun-Solaris, SGI-IRIX, HP-UX, IBM-AIX, Compaq Tru64 UNIX and Digital Unix.

PPDs from Linuxprinting.org:

Those are a way to make any previously working pair of Ghostscript-filter / printer-device work with CUPS. You'll usually get the same (good or bad) printing quality as in standard LPR/LPD or LPRng print system installations. But in addition you'll have all the CUPS goodies: web interface, access to all supported printer/driver/filter options (through commandline, GUI or web interface), etc. This concept is lately also known as "Foomatic". For it to work, you do not just need the Foomatic PPD (which may be generated online on the Linuxprinting.org website), but also the accompanying cupsomatic Perl script (download it too), plus working Perl and "standard" Ghostscript installations on your box. Unfortunately some Linux distributions have bundled alpha and beta versions of this software without any documentation, which leads in many cases to difficulties and outright failure to setup a printer. cupsomatic, if it works, "hi-jacks" your print data after it has passed the CUPS pstops filter, hands it to the appropriate Ghostscript filter, which generates the print-ready output and gives it back to the CUPS backends to pass it to the target printer.

PPDs from the Gimp-Print project:

Those are distributed as part of the gimp-print software source code. If you compile it with CUPS support enabled (./configure --with-cups), you get everything installed into the right places in CUPS, including specific PPDs for around 120 different models of Canon, Epson, HP and Lexmark color printers. The creators of CUPS are founders and still part of the development team of gimp-print project.

So not every PPD works with every filter. Nor is a PPD the *only* file you need to make your printer work. Any PPD for a non-PostScript printer is associated with a companion filter that is needed for it to work.

Only if you own or have access to a PostScript printer, it is good enough to copy the PPD from a friend's box. If you want to use the gimp-print software, the PPD is only part of the cake. *You also need to have the Gimp-Print filters installed for the Gimp-Print PPD to function as expected!* And don't rely a CUPS-O-Matic generated PPD to work with a PostScript printer! This is generally a bad idea. PostScript printers should be installed using the vendor PPD for that model (best use the one targeted for Windows NT).

You can do a lot to de-bug a not working printer:

How to tell your printer's PPD

For every installed printer (apart from "raw" printers), there is a copy of the companion PPD in the /etc/cups/ppd/ directory, named like your printer with a .ppd extension. (Hint: you don't need to put this file manually there; it's done by the lpadmin command or the web installation interface). Example: a printer named "MySuperDuperInkjet" will have a /etc/cups/ppd/MySuperDuperInkjet.ppd. A nice trick: You can look at a PPD in use for a particular printer through your browser (if your CUPS daemon is running) by pointing it to http://localhost:631/printers/MySuperDuperInkjet.ppd. Amongst the first 25 lines of this file you should recognize lines like the following:

*PCFileName:    "escp2-1290.ppd"
*Manufacturer:  "EPSON"
*Product:       "(GIMP-print v4.1.99-b1)"
*ModelName:     "escp2-1290"
*ShortNickName: "EPSON Stylus Photo 1290"
*NickName:      "EPSON Stylus Photo 1290, CUPS+GIMP-print v4.1.99-b1"

Most important is the line starting "*NickName...". It should always be there and tell you which sort of PPD is in use. Supply this information, if it is related to your problem!

(If you are not able to access the file through you browser, the command "head -n 25 /etc/cups/ppd/MySuperDuperInkjet.ppd" will also get you there.)

Amongst possible tags for the PPDs you might find things like:

Supply this little piece of information; most of the time it is important.

How to tell which filters are in place (and maybe failing?) or missing

Switch on the "debug" mode in the LogLevel directive for your CUPS daemon. Edit /etc/cups/cupsd.conf (or wherever this configuration file is installed in your case) to have the line "LogLevel debug" there. Then restart your CUPS daemon /etc/software/init.d/cups start (the command may be customized by your Linux distribution; f.e. SuSE will take "rccups start").

Now print a job. Watch what is written to your CUPS error log. It normally sits in /var/log/cups/error_log. In debug level, nearly every action of the CUPS daemon is logged. You can see which filters and backends are called in which order. Very often you'll get a hint about what is missing for the print job to succeed.

A telling example of the error_log in "debug" mode

An example that recently dropped into my mailbox. Some parts are deleted. Look at it. Do you spot the problem? Have a try:

d [04/Sep/2001:21:38:28 +0100] SendBrowseList: (97 bytes) 100e 3 
                                ipp://mama:631/printers/hp720c "Dach" 
                                  "HP DeskJet 720C, Foomatic + pnm2ppa"
D [04/Sep/2001:21:38:29] StartJob(22, 080868b0)
D [04/Sep/2001:21:38:29] StartJob() id = 22, file = 0
D [04/Sep/2001:21:38:29] StartJob: argv = "hp720c","22","root",
                          "Test Page","1","","/var/spool/cups/d00022-001"
D [04/Sep/2001:21:38:29] StartJob: envp = "PATH=/bin:/usr/bin",
D [04/Sep/2001:21:38:29] StartJob: statusfds = 7, 8
D [04/Sep/2001:21:38:29] StartJob: filterfds[1] = 9, -1
D [04/Sep/2001:21:38:29] StartJob: filter = "/usr/lib/cups/filter/pstops"
D [04/Sep/2001:21:38:29] StartJob: filterfds[0] = 10, 11
D [04/Sep/2001:21:38:29] start_process("/usr/lib/cups/filter/pstops", [....])
I [04/Sep/2001:21:38:29] Started filter /usr/lib/cups/filter/pstops 
                          (PID 935) for job 22.
D [04/Sep/2001:21:38:29] StartJob: filter = "/usr/lib/cups/filter/cupsomatic"
D [04/Sep/2001:21:38:29] StartJob: filterfds[1] = 9, 12
D [04/Sep/2001:21:38:29] start_process("/usr/lib/cups/filter/cupsomatic", [....]
I [04/Sep/2001:21:38:29] Started filter /usr/lib/cups/filter/cupsomatic 
                          (PID 936) for job 22.
D [04/Sep/2001:21:38:29] StartJob: backend = "/usr/lib/cups/backend/parallel"
D [04/Sep/2001:21:38:29] StartJob: filterfds[0] = -1, 10
D [04/Sep/2001:21:38:29] start_process("/usr/lib/cups/backend/parallel", [....])
I [04/Sep/2001:21:38:29] Started backend /usr/lib/cups/backend/parallel 
                          (PID 937) for job 22.
d [04/Sep/2001:21:38:29] SendBrowseList: (97 bytes) 100e 4 
                           "Dach" "Farbdrucker" 
                            "HP DeskJet 720C, Foomatic + pnm2ppa"
D [04/Sep/2001:21:38:29] CloseClient() 5
D [04/Sep/2001:21:38:29] CloseClient() 3
D [04/Sep/2001:21:38:29] EBUG: Page = 612x792; 9,40 to 603,766
D [04/Sep/2001:21:38:29] pw = 594.8, pl = 726.9
D [04/Sep/2001:21:38:29] PageLeft = 8.6, PageRight = 603.4
D [04/Sep/2001:21:38:29] PageTop = 766.5, PageBottom = 39.6
D [04/Sep/2001:21:38:29] PageWidth = 612.0, PageLength = 792.0
D [04/Sep/2001:21:38:30] Cupsomatic backend version $Revision: 1.3 $ running...
D [04/Sep/2001:21:38:30] called with arguments: '22','root','Test Page','1',''
D [04/Sep/2001:21:38:30] ppd=/etc/cups/ppd/hp720c.ppd
D [04/Sep/2001:21:38:30] options: -><-
D [04/Sep/2001:21:38:31] gs PID pid2=939
D [04/Sep/2001:21:38:31] /usr/lib/cups/filter/cupsomatic: prepended:
D [04/Sep/2001:21:38:31] gs command: gs  -sDEVICE=ppmraw  -q -dNOPAUSE 
                          -dSAFER -dBATCH -r600  -sOutputFile=- - | pnm2ppa
                           -v 720 -f /etc/pnm2ppa.conf --eco 
                            -F /etc/pnm2ppa.gamma_normal -B 2   -t 10 
                             -b 150 -l 10 -r 10 -x 160 -y 50 -i - -o -
D [04/Sep/2001:21:38:31] sh: pnm2ppa: command not found
D [04/Sep/2001:21:38:31] foomatic-gswrapper: gs '-sDEVICE=ppmraw' 
                          '-dNOPAUSE' '-dSAFER' '-dBATCH' '-r600' 
                           '-sOutputFile=|cat >&3' '-' 
                            3>&1 1>&2
D [04/Sep/2001:21:38:31] GNU Ghostscript 5.50 (2000-2-13)
D [04/Sep/2001:21:38:31] Copyright (C) 1998 Aladdin Enterprises, 
                          Menlo Park, CA. All rights reserved.
D [04/Sep/2001:21:38:31] This software comes with NO WARRANTY: see the file 
                          COPYING for details.
D [04/Sep/2001:21:38:32] Loading NimbusSanL-Bold font from 
D [04/Sep/2001:21:38:32] Loading NimbusSanL-Regu font from [....] done.
D [04/Sep/2001:21:38:33] Loading NimbusRomNo9L-Regu font from [....] done.
D [04/Sep/2001:21:38:34] Loading NimbusSanL-BoldItal font from [....] done.
D [04/Sep/2001:21:38:35] cat: write error: Broken pipe
D [04/Sep/2001:21:38:37] mallinfo: arena = 550944, used = 521384, 
                          free = 29560
D [04/Sep/2001:21:38:49] Error: /ioerror in --.outputpage--
D [04/Sep/2001:21:38:49] Operand stack:
D [04/Sep/2001:21:38:49] 416.5  308.0  306.0  748.0  306.0  
                          55.0  51.0  1  true
D [04/Sep/2001:21:38:49] Execution stack:
D [04/Sep/2001:21:38:49] %interp_exit  .runexec2  --nostringval--  
                          --nostringval--  --nostringval-- 2  %stopped_push  
                           --nostringval--  --nostringval--  --nostringval-- 
                            false  1  %stopped_push  1  3  %oparray_pop  
                             .runexec2  --nostringval--  --nostringval--  
                              --nostringval--  2  %stopped_push  
                               --nostringval--  7  3  %oparray_pop   
                                --nostringval--  --nostringval-- 
                                 --nostringval--  --nostringval--
D [04/Sep/2001:21:38:49] Dictionary stack:
D [04/Sep/2001:21:38:49] --dict:918/1241(G)--  --dict:0/20(G)--  
D [04/Sep/2001:21:38:49] Current allocation mode is local
D [04/Sep/2001:21:38:49] Last OS error: 32
D [04/Sep/2001:21:38:49] Current file position is 14608
D [04/Sep/2001:21:38:49] GNU Ghostscript: Unrecoverable error, exit code 1
D [04/Sep/2001:21:38:49] tail process done writing data to *main::STDOUT
D [04/Sep/2001:21:38:49] UpdateJob: job 22, file 0 is complete.
D [04/Sep/2001:21:38:49] CancelJob: id = 22
D [04/Sep/2001:21:38:49] StopJob: id = 22
D [04/Sep/2001:21:38:49] StopJob: printer state is 3

Did you spot the problem? Yes, on 04/Sep/2001, at 21:38:31, the system was looking for, but could't find or execute the pnm2ppa filter. Although the user didn't supply any information about his system, one can see and conclude, what his environment is like:

What is wrong here?

Some background first: the HP DeskJet720C is a so called PPA printer. PPA has been developed by Hewlett-Packard in the mid-90s and was soon after dropped again. It stands for "Print Performance Architecture" and due to little market success was only used in a few models. The idea in PPA was to make a cheap printer, saving on electronics inside the device. The complete rendering must be done by the printing host. Of course there were only drivers by HP for the windows platform.

Now pnm2ppa is a filter that can convert PNM ("Portable Anymap") to the PPA format. There are three different PNM variants: PPM (Portable Pixmap, color), PGM (Portable Graymap)and PBM (Portable Black-and-White-map). pnm2ppa is *not* a part of Ghostscript. It has to be installed separately. You can find it at http://pnm2ppa.sourceforge.net/ or http://sourceforge.net/projects/pnm2ppa/). In SuSE it is part of the "filters" package. To print to the printer in question, you still need Ghostscript, namely to *create* the PNM from the original PostScript. The Ghostscript-"devices" ppmraw, pgmraw or pbmraw will do this from PostScript input. The conversion chain and travelling route of the print file through the system could therefor be described like this: PostScript --> ppmraw --> PNM --> pnm2ppa -->PPA --> HP720C printer.

As you can see from the error_log, it stops at the pnm2ppa stage because this filter is not installed or can not be found or executed by the cupsomatic "backend"...

Posting Configuration Files

If you find it appropriate to send your cupsd.conf configuration file to the ones you ask for help, please strip it as far as possible. We don't necessarily want to scroll through all the comments. A command like

cat /etc/cups/cupsd.conf|grep -v ^#|grep [:alnum:]

will print your cupsd.conf file onto the screen without the comment lines (starting with a "#" character), and

cat /etc/cups/cupsd.conf|grep -v ^#|grep [:alnum:] > cupsd.conf-stripped

will re-direct this output to the file cupsd.conf-stripped. It looks f.e.like this:

   ServerAdmin root@transmeta
   Classification none
   DefaultCharset UTF-8
   DefaultLanguage en
   Printcap /etc/printcap
   PrintcapFormat BSD
and contains only ~80 lines (1500 characters) instead of ~800 lines (18.000 characters).

Other Items to Check

Recent versions of CUPS help you determine a few things. The utility cups-config has several optional parameters, shown by calling "cups-config --help".Its output is:

kurt@transmeta:~> cups-config --help
Usage: cups-config --api-version
       cups-config --cflags
       cups-config --datadir
       cups-config --help
       cups-config --ldflags
       cups-config [--image] [--static] --libs
       cups-config --serverbin
       cups-config --serverroot
       cups-config --version

If you ask it questions, f.e. "cups-config --libs", it will tell you which libraries have been used to compile into it. So if you are looking for SSL support and there is no "-lssl" output to your question, you get a hint how to help yourself.

To determine which static libraries are linked to your cupsd executable, use the ldd command (as root). Here is what's on my system:

transmeta:/home/kurt/cups-versionen # ldd `which cupsd`
        libz.so.1 => /lib/libz.so.1 (0x4002e000)
        libssl.so.0.9.6 => /usr/lib/libssl.so.0.9.6 (0x4003d000)
        libcrypto.so.0.9.6 => /usr/lib/libcrypto.so.0.9.6 (0x4006a000)
        libpam.so.0 => /lib/libpam.so.0 (0x40133000)
        libdl.so.2 => /lib/libdl.so.2 (0x4013c000)
        libcups.so.2 => /usr/lib/libcups.so.2 (0x40140000)
        libnsl.so.1 => /lib/libnsl.so.1 (0x4015a000)
        libcrypt.so.1 => /lib/libcrypt.so.1 (0x40171000)
        libc.so.6 => /lib/libc.so.6 (0x4019e000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

This output even shows you, which SSL-version has been used (0.9.6), in case you need to know for troubleshooting....

RedHat-specific problems with CUPS and KDEPrint

If you're wondering, why your standard RedHat KDEPrint command kprinter does not support CUPS, check if the following files are in place on your system:

If those files are not installed on your system, then the possible reasons are:

Where to ask...

Please be very hesitant to write mails to private addresses of people you know answering questions in public forums. Don't expect them to react dutifully on unsolicited personal mails. Start asking in the suggested public forums and only send material to private mail addresses if asked to do so. Asking on a public list will enable everybody to learn from the given answers. It increases your chance to get a quick response, as there might be different people watching the list fit for giving advice. Remember, this is a volunteer service. Sometimes people are tired to answer. Can you imagine that someone might feel molested by receiving 20 - 30 personal mails per day, asking the same questions about printing over and over again? It is OK to ask the questions -- but keep it voluntary for your advisors, as it is the case, if you ask in the following public forums or on mailing lists:


The home of the CUPS-centered newsgroups and a mailing list.


The resource to look for answers if you have vendor- or model specific questions. There is a separate forum for all major manufacturers.


Here you'll probably find the best help for all problems concerning "Foomatic" usage along with CUPS.


This is the place of choice if you are suffering from difficulties with using Gimp-Print drivers.


Find documents about printing with the KDEPrint GUI here.


Subscription page for the kdeprint mailing list.


Search the archive of the kdeprint mailing list.

Ready to ask!

Now that you have read all the suggested stuff and thought about your problem again: do you still need to ask? If so, you're welcome. But please, supply the facts you have...

Kurt Pfeifle (kpfeifle@danka.de)

(Version 0.92, February 2002)