Linux Foundation Wiki

project collaboration site

User Tools

Site Tools


beh - The Backend Error Handler

Very annoying with CUPS is that when an error on the communication between the CUPS backend and the printer occurs, CUPS disables the print queue and to be able to continue printing an administrator (root access required) has to re-enable the queue. It is not enough to simply fix the printer's communication problem (like turning it on, fixing the network connection, …).

This is especially a very bad design for desktop/home users. They often only turn on their printers when they really want to print (to save energy). Then it happens easily that they send a job and forget to turn on the printer. CUPS disables the queue and the annoying re-enabling procedure has to be done. And many users even do not know about the problem. So the printer does not print and the queue gets nuked and re-created. Or the people cry on the help forums or at the installation support of their distributions.

This problem can be easily worked around by installing beh, the Backend Error Handler. This script makes the handling of such backend errors configurable, so that the problem can easily be worked around. The new possibilities are:

  • Let queues simply not being disabled. Simple approach, but job gets lost.
  • Repeat a given number of times.
  • Repeat infinitely often, until the job gets finally through. This is the standard of LPRng, and it eliminates loss of the job.
  • The interval between two attempts to run the backend can also be configured.
  • Configuration is done independently for each print queue. So local printers and network printers can be treated differently.

Simply download the script, copy it into the CUPS backend directory (normally /usr/lib/cups/backend/), and make it executable with “chmod 755 beh. Then restart CUPS that it registers the new backend, usually with ”killall -HUP cupsd“ or ”/etc/init.d/cups restart“. If you did all correctly, there must be a line containing ”beh“ in the output of ”lpinfo -v“.

beh is a wrapper which is called by CUPS in place of the usual backend, which is called by beh now. This way beh can, depending on its configuration, repeat the call of the backend or simply hide the error status of the backend from being seen by the CUPS daemon.

To make a print queue using beh, get root and call a command as follows:

lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri>


  • <queue name>:
  • The name of your print queue
  • <dd>:
  • Don't Disable, if ”1“, beh always exits with zero status, so the queue gets never disabled when the original backend exits with an error. ”0“ carries the error status of the last call of the backend (after <att> retries) on to CUPS, so the queue usually gets disabled.
  • <att>:
  • Attempts, number of attempts to recall the backend in case of an error. ”0“ means infinite retries. In this case <dd> gets meaningless.
  • <delay>:
  • Delay between two attempts to call the beckend, to be given in seconds and as an integer number. Meaningless if <att> is one.
  • <originaluri>:
  • The original URI, which your queue had before (use ”lpstat -v“ to get your queue's URI shown).

All parameters, especially, <dd>, <att>, and <delay> have always to be specified, even if one of them is meaningless due to the setting of the others.

beh works with every backend except the hp backend from HPLIP. If beh is used with the hp backend, the HP Toolbox will not find the printers any more.

Example URIs:

On the network printer with host name ”printer“ it is tried to access 3 times with 5 second delays between the attempts. If the job still fails, the queue is not disabled (and the job discarded).

Retry 10 times in one minute intervals, disable the queue when still not succeeding.\

On a Brother HL-5040 on the USB try infinitely often until the printer comes back, in intervals of one minute. This way the job does not get lost when the printer is turned off and one can intendedly delay printing by simply switching off the printer. The ideal configuration for desktop printers and/or home users.

Print accounting is usually done by a wrapper backend provided by the accounting software. You can also use beh in combination with accounting, if you choose the correct order for the wrapper backends.

I (Till) have tried out pykota and accsnmp. For accsnmp only the version


works, but as accsnmp being a pure hardware accounter, wrong accounting by the retries of beh can never happen. Only exception would be if the real backend has a bug leading to an error exit when the job has actually been printed (but then the real backend should not be used with beh anyway). The other way arround (accsnmp://beh:/1/0/30/…) does not work (Already reported to the author of accsnmp).

In case of pykota with hardware accounting it only works with:


So this version has to be used for hardware accounting. And as hardware accounting only counts actually printed pages there is no problem of the cupspykota backend being called repeatedly. On all unsuccessful attempts (printer off, no paper/toner, …) cupspykota counts zero pages with hardware accounting.

With software accounting both orders of beh and cupspykota work, but here the recommended form is to let cupspykota call beh to avoid repeated counting of the pages if the printer fails.

So for now beh and accounting software should be combined as follows:




  • Hardware accounting
  • beh:/0/3/5/cupspykota://socket://
  • Software accounting
  • cupspykota://beh:/0/3/5/socket://

In general

  • Always the accounter first if possible, especially when using software accounting
  • Use hardware accounting whenever possible (as then always only the actually printed pages are counted)

Report bugs to our bug tracking system (Component: foomatic-filters).

openprinting/database/backenderrorhandler.txt · Last modified: 2016/07/19 01:20 (external edit)