This site is now 100% read-only, and retired.

Using the Debian bug-tracking system

Posted by jamesw on Tue 29 Aug 2006 at 09:19

Debian makes heavy use of it's bug-tracking system, (BTS) to coordinate work, and for developers to know that a problem needs fixing.

This article is aimed at those who haven't seen the BTS before, or know who have used it a little, but would like to know about how to manipulate bugs.

Viewing the bugs

If you want to see what bugs have been reported to the BTS this is easy to do using the web interface. This is accessible at If you go to this page you can see a form for searching the bug reports. The system is package based, so you can enter the name of a package and search for all bugs related to that package.

For example, enter apt in to the search box, and make sure the package option is selected just above it. Then click the find button. This will then show the page with all of apt's bugs on it. You can click on any of the bug titles to see more information on the bug.

There are also shortcuts that you can use e.g. for all apt's bugs and for bug #383487.

States, Severities and Tags.

You can see that the bugs are divided up in to sections. These sections are based on the states that the bugs are in, and the severities that were assigned to them. This helps the maintainer of the package to see what needs doing, and to prioritise their work.

The states of the bugs are:

  • Open - The bug is not fixed.
  • Forwarded - The bug has been reported to the upstream maintainer as it requires work on their part.
  • Resolved - The bug has been fixed.

The severities are:

  • wishlist - The submitter would like some extra feature to be added to the package.
  • minor - There is something wrong with the package that doesn't really matter, but should be fixed anyway. This could be for a typo in the package description, for example.
  • normal - This is where most bugs belong. There is a problem with the package, but it doesn't break the whole thing, or cause too much trouble.
  • important - This is a bug that has a big impact on the usability of the package.

These are the severities that you will normally use. There are three more severities, and they have special meanings. They also get special treatment when they are not being fixed. You should only really report a bug at one of these severities if you understand what they mean. Don't worry though, if you report a bug that deserves to get one of these severities it will be upgraded.

  • serious - A violation of the Debian Policy. The rules set out in the Policy aim to make sure that a package will not break a system it is installed on, as well as trying to make packages consistent. Have a look at the policy document if you are interested.
  • grave - A bug that renders the package unusable in all or nearly all situations. This would cover things like uninstallable packages, segmentation faults on startup, missing files. It should only be used when it breaks the software for most users though, it can be tricky to know when this is the case, but experience helps. This severity also covers some security holes.
  • critical - Installing the package breaks other unrelated software on the system, or indeed the whole system. This also covers programs that cause data loss and the rest of the security bugs.

Tags are used by developers to keep track of what is happening to the bugs. A full list is available at Some of the most common ones you will see are:

  • patch - someone has supplied a patch that fixes the problem. This does not apply for workarounds.
  • wontfix - the maintainer or upstream developer has said they will not fix the bug for some reason. There will usually be an explanation in the bug report.
  • moreinfo - the submitter did not provide enough information to the maintainer. If you are hit by a bug with a moreinfo tag then you should follow up (see below) with the information the maintainer wants.
  • unreproducible - the maintainer can't reproduce the bug on his system. This is similar to the moreinfo tag, in that if you can reproduce you should help the maintainer by sending more information to the bug report.
  • help - the maintainer can't fix the bug by themselves (for example it only occurs on an architecture they do not have access to), and would like other people to help come up with a solution.
  • pending - The problem is solved and an upload should happen soon to fix it.

Some of the other tags are either obvious (e.g. security) or are used more for tracking things across the distribution (e.g. ipv6).

Reporting a bug

If you find a bug that you would like to see fixed then you have to use the BTS to make the maintainer aware, and work with them to fix it. So to start off you need to report the bug.

Before you report it though there are a few things you need to do.

  1. Work out what package the bug comes from.

    • Sometimes this is very easy, and you will instantly know the package.
    • If you only know that it occurs because of a certain file or program, you can use dpkg -S with the filename to find out the package that it belongs to.
    • If you can not work it out, then you will have to make a best guess, and you can report it to that package. You should note in the report that you are only guessing, and the maintainer of that package will try and help you work it out.
  2. Find if the bug has already been reported.

    • Use the package search to see the bugs for the package and look for your bug in the list. If it is there then do not report a new bug, you can add more information to it, see below.
    • You may need to check a few associated packages to make sure that you didn't get the responsible package slightly wrong.
  3. Gather as much information as possible. Ideally the report should contain:

    • The steps to reproduce, i.e. the complete sequence of commands used to trigger the problem.
    • Any relevant configuration files, or the options from the program.
    • Any relevant log files. You can attach them to your report (see below).
    • Any other information you think might help.
    • Any workarounds you may have found, or anything interesting you have noticed about the bug.
    • If you know how you can include a backtrace from gdb, or the output of strace. These can be invaluable in some cases.

Now you have all this information you are ready to report a bug. The preferred way to do this is to use the report bug program, so

    # apt-get install reportbug

And the simply run

    $ reportbug

There are many options you can pass to reportbug (man reportbug will help you there), but reportbug will walk you through the steps needed to send the report.

So first you are asked for the name of the package that you wish to report a bug against.

    Please enter the name of the package in which you have found a problem, or type
    'other' to report a more general problem.

Once you have entered the name of the package you will be shown the list of bug reports already filed against the package. Make sure your bug is not listed and continue. If it is listed then you can send more information (see below).

When you have checked the bug reports, you will be prompted for the subject of the bug report.

     Please briefly describe your problem (you can elaborate in a moment; an empty
     response will stop reportbug). This should be a concise summary of what is
     wrong with the package, for example, "fails to send email" or "does not start
     with -q option specified."

Some people like to start this with the name of the package (though it is not essential), e.g.

     apt: does not download correct version of dpkg

You will then be prompted for the severity of your report. Select a number from the list that you think best applies. If you are unsure just hit Enter and you will get the default normal and the maintainer can change it if need be.

reportbug may then ask you if it can include some of your configuration files in the report. You should answer yes, unless the files contain sensitive information (e.g. passwords).

An editor will then be spawned for you to write you bug report. Fill in all the information that you found above, then save the file and close the editor.

You will then be shown the final menu

    Report will be sent to "Debian Bug Tracking System" 
    Submit this report on apt (e to edit) [y|n|a|c|E|i|l|m|p|q|?]?

There are many options here. Type ? to get a list. The interesting ones are

  • e - edit the report again
  • a - attach another file (e.g. log file, gdb backtrace)
  • y - send the report via email.

When you have finished choose y to send it (or if you require you can use the other options to send it your self). That is then it, you have submitted your first report.

You will receive a copy of the report straight away, and the confirmation from the BTS within the hour.

It is possible to report bugs via email as well if you want. Instructions are given at Not using reportbug has the disadvantage that you must do more by yourself, as you don't have reportbug's checks, or automatic inclusion of some information.

Following up to bugs

If you wish to send more information to a bug report there are two ways to do it.

  • Use reportbug again.
  • Use email.

I wont describe the reportbug way in too much detail, as it provides you with help, and is similar to the procedure above.

To use report bug to send a followup to a bug start reportbug and enter the package name. Then when the list of bugs is displayed press y, which will prompt for the bug number. You can then proceed as before. If you see the bug in the list it shows you enter the number from the left hand side, and reportbug will show you the bug report. If you enter x at the prompt then you will provide a follow-up to that bug.

To send information by email you just need to send an email to, e.g. The content of the email will then become part of the bug report.

Whichever method you use it is useful if you don't simply send an email like

    Subject: Bug #12345

    I am seeing this bug as well, can I help fixing it?

as, while it is good to offer your help, it requires anyone who receives that email (and the emails do go to a few places), to go and look up the bug. It would be better to send something like:

    Subject: Re: Bug#13245: apt doesn't download correct version of dpkg

    I am also seeing this bug. I have tried giving the version on the
    command line to apt, but it still downloads version 1.2.3 of dpkg.

    Is there anything else I can do to help?

It says the same thing, but provides much more context to those who receive the email, so they can simply reply to your email if they want, without having to go and look up the report.

Manipulating bugs

You can manipulate bugs using the email interface. This involves sending and email to with a certain format. The message is then processed, and the instructions in it are executed.

The full documentation on how to do this is at and is good for a reference.

A sample email might look like

     #only consider bugs that are assigned to apt
     package apt
     #change the severity of a bug
     severity 12345 normal
     #reassign a bug
     reassign 12345 dpkg
     #stop processing commands

The comments are optional and only used here to try and illustrate what is happening. The stop command is useful so that the server doesn't process any more of the email and get confused.

Closing and reopening bugs

If you wish to close a bug report (normally only the submitter or the maintainer do this), you can send an email to and include a Version: pseudo-header that tells the system in what version the bug was fixed. e.g.


     Version: 1.2.3

     This is fixed in the latest upload. Thanks for your patience.

The version is used so that it is possible to track when a bug was opened and closed, so that it is known which versions a given bug applies to.

If you discover a bug that has been closed, but re-occurs in a later version, you can send an email with a found command to (see above), e.g.

     found 1234 1.2.4

     I have found this in version 1.2.4, it occurs in the same conditions
     as before.

You should only do this if it is the same bug though. Submit a new one if you find a new bug.

Other tricks

There are many other things you can do with the BTS. I will let you figure out how to use them. The documentation at covers most of them.

  • bts tool - The devscripts package contains a tool called bts. This is a quick way to send commands to the BTS. e.g. bts severity 12345 normal
  • subscriptions - It is possible to subscribe to a bug report, so that you receive all information sent to the report, and can find out when it gets closed.
  • usertags - allow you to tag bugs for yourself. Other people looking at reports wont normally see them. These are most often used by maintainers who look after a lot of bugs so they can be categorised or prioritised.



Re: Using the Debian bug-tracking system
Posted by wuzzeb (72.1.xx.xx) on Tue 29 Aug 2006 at 18:11

I found a minor bug in the article... I suppose I better report it :)

In any case, from the description of critical "Installing the package breaks other unrelated software on the system, or indeed the while system."

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by jamesw (82.32.xx.xx) on Tue 29 Aug 2006 at 22:18
Fixed. Thanks.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by glenny (82.67.xx.xx) on Tue 29 Aug 2006 at 21:40
There is an alternative if you don't want use a web browser. This tool is called 'querybts' and provided by 'reportbug' package. It has nice cli user interface (using newt).
-- Glennie

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by Anonymous (87.69.xx.xx) on Fri 1 Sep 2006 at 20:26
Thank you, this is a great review for people new to debian.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by purves (198.166.xx.xx) on Wed 27 Sep 2006 at 21:27
What user should be used for reporting bugs? If I run reportbug as root, reportbug tells me not to, that it's a security risk. If I run reportbug as a regular user, version information is missing presumable becuase that user does not have permission to run dpkg.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by jamesw (82.32.xx.xx) on Wed 27 Sep 2006 at 22:22
Any user has access to run dpkg by default, so this seems odd.

Yes you should run reportbug as your normal user, however I cannot tell you why
it doesn't work for you I'm afraid.

Can you confirm that you are not able to run dpkg from the command line (use
a command that doesn't require you to be root (e.g. -l)? If
so you should sort out the permissions on the executable. If you are able to
then you have some other problem.

Maybe I should have included something in the tutorial about setting up
reportbug's environment, sorry about that.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by purves (198.166.xx.xx) on Wed 27 Sep 2006 at 23:54
I checked the permissions for /usr/bin/dpkg and it was set to 750. The other dpkg-* binaries were 755. I reset to 755 and reportbug now includes the version information.

Thanks for your help.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by lamby (85.211.xx.xx) on Sat 21 Apr 2007 at 03:05
For anyone still bumping into this via a search engine - look for the reportbug-ng package for a graphical way to report bugs.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by zdf (222.180.xx.xx) on Wed 25 Jul 2007 at 05:36
is it possible to reply to a specific follow-up within a specific bug?

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by jamesw (82.32.xx.xx) on Wed 25 Jul 2007 at 17:36
A follow-up that you received, or a follow-up you found via the web interface? For the former simply replying to the bug is enough. For the latter there are two things you could do. You can get the "Message-ID" from the "full text" link above the comment and use that in a "Reply-To" header in your reply. You can also use the "mbox" link to get a copy of the message in mbox format and reply to that. However it is probably just easiest to email the bug (and the author of the message if it is not the maintainer), and quote the message. Whatever method you choose your reply wont show up directly underneath the one you are replying to, unless it is currently the last message.

[ Parent ]

Re: Using the Debian bug-tracking system
Posted by zdf (222.183.xx.xx) on Wed 25 Jul 2007 at 18:15
very helpful comment, thanks a lot!

[ Parent ]