How to Deal with a "filter failed" error in CUPS

 I ran across this error recently when I installed a new Linux distribution on my writing computer called "Neptune OS", which is a Debian based distro. I spent about 2 days troubleshooting this problem, and I finally ran across the solution (at least in my case) that allowed me to print again.

So, installed this distro that I wanted to try out for my channel series: "New User Linux Reviews." I installed it, which went smooth enough, Then, in checking out the distro, one of the functions I check out was whether the system installed the printer (I have a network printer, a Brother MFC-L2710DW) or not, how easily it was to install it if it didn't, and did it work or not?

So when I went to check out the printer, I was pleasantly surprised to find the printer had been automatically detected and installed. So I initiated a test page print to see if it would print. Unfortunately, it didn't. And the only error message I found was "filter failed," which I discovered in my research could be caused by several different issues.

Probably the best troubleshooting guide that I found on the web was in the Arch Wiki:

https://wiki.archlinux.org/index.php/CUPS/Troubleshooting#CUPS:_%22Filter_failed%22 

It listed several of the major reasons it could give that error, as well as what to do about them, though it failed to give me a solution to my problem. Still, it pointed me in the right direction to figuring out, quite by accident, my solution.

After scouring the web for potential causes and solutions to this problem, and coming up empty handed, I realized that there wasn't much out on the web to help people address this issue (thus, the reason for this blog post). So after finding the Arch Wiki article mentioned above, I read through my error_log file in

/var/logs/cups/

That is when I discovered that the problem was an app called "pdftopdf" that it failed to create a "log file." Which created a cascade effect of other apps--that CUPS relies upon--to error out as well. Since some of those apps are also cups filters, it gave me the "filter failed" error in the print queue.

But, I still had to figure out what to do about it. After trying out a few other options, and they failed as well, I finally noticed one error message in the error_log file, which read: 

open /usr/share/cups/data/default-testpage.pdf: no such file or directory

On a whim, I decided to go to that directory and find out what was there. What I found were several pdf files that I realized were templates. However, what I also noticed was a file called

default-testpage.pdf.XXXXX

The "XXXXX" stands for some other letters that started with a "C" but I've already forgot exactly what they were (I'm not even sure about the "C" either). I wondered what would happen if I deleted  the extra letters from the end of that file so that it ended in "pdf," whether it might not find the file and print it. So I did that, then I went back to the printer queue and hit the "reprint" button: it printed!

Okay, so that meant that the CUPS system wasn't coordinating with what the printer was looking for as far as file names. I suspected it might be the CUPS system which was at fault, since I've had this printer for some time now, and have installed it on multiple systems without much issues, save for Arch distros, which while they install CUPS, rarely appear to have their daemon active, much less a GUI print manager application installed.

From that data, I wrongfully concluded that the two files I had noticed in that directory (default-testpage.pdf.XXXX, modified to default_testpage.pdf and file testprint which I had modified to testprint.pdf, were still there. I had assumed that these files were temp files that would disappear once they printed. I should have known better, however, that these were templates with names like "standard.pdf, secret.pdf, topsecret.pdf, classified.pdf and unclassified.pdf just to name a few of the other files in the directory.

However, what caused me to realize that bit of truth were the messages that now popped up on all three of the printers I had installed on the system that said something about a missing file, in bright red at the top, and they failed to even acknowledge that I had printed a test page, nothing in the print queue, nothing in the error_log file save something about not being able to create a profile or something along those lines. That is, once I deleted those two files.

So, what was I to do? That's when I wondered if my Linux Mint CUPS folders on my laptop might have the same list of files, like, maybe I could use those files? So I checked and they did have those same files. So I copied them all over to the same directory on my desktop, and guess what? Suddenly, the printers worked!

All I can figure was that one or more of those files were corrupted and/or the printer was looking for names that CUPS had given different names to use as templates. Not finding the expected template pdf file, it crashed. Once I changed the name of that one file, the printer was able to print the file. In copying over the files from a working copy of CUPS in this directory only, I somehow fixed the system.

So for everyone out there who has the same error in the error_log file, that could be your issue and solution as well.

May the Linux Force be with you!

 

UPDATE (3/14/21): I reinstalled the system and here is the file I noticed with the extra ending on it in the PDF templates that are in the /usr/share/cups/data directory:

default-testpage.pdf.distrib

I also printed out a normal text from the Kwrite program successfully, before I ever changed anything. The printer works out of the box. The only part that doesn't appear to work is the test page which should print out when you select "Print Test Page" under the maintenance button on the "Printers" section of the System Settings.

Once I had confirmed that everything else would print, I removed the ".distrib" ending so that the file read: default-testpage.pdf, which is exactly the file name that the error log said CUPS was looking for. Once I made that one change, it would print the test page just fine.

So, the bottom line is that to fix this apparent error, all one has to do is change the file name from:

default-testpage.pdf.distrib

to:

default-testpage.pdf

And you'll be good to go!

You can do that by entering the following command at a terminal prompt:

mv /usr/share/cups/data/default-testpage.pdf.distrib /usr/share/cups/data/default-testpage.pdf

May the Linux force be with you!