If you have any doubt about this guide, you can ask any time.
Many times, a problem you're running into isn't a bug in Ubuntu, but rather a problem resulting from your setup, a mistake, or a difficult-to-reproduce glitch. Even if you have found a legitimate bug, making a proper bug report is somewhat of a skill in and of itself. If you're in doubt, or if you don't have the time to learn how to do bug reporting, Ubuntu provides several live chat support channels on Libera.Chat, which you can browse through here: https://wiki.ubuntu.com/IRC/ChannelList. Volunteers here can walk you through how to debug the problem you've run into, and potentially help you fix it, and file a bug report if necessary.
If you're sure you've found a bug, and are interested in learning proper bug reporting, the rest of this guide will walk you through the bug reporting process for Ubuntu.
How to report bugs
Ubuntu uses Launchpad to keep track of bugs and their fixes. This page will guide you through the steps required to file a good and detailed report.
When possible, this will involve running a command 'ubuntu-bug' alias 'apport-bug' alias 'apport-collect'
that will collect information from the local system on the problematic program, and then open a form in a web browser for your comments.
Create a Launchpad account
If you don’t already have one - you need to create a Launchpad account. This will allow you to file new bugs and comment on existing ones.
Determine if the bug is really a bug
You should not file a bug if you are:
Requesting new software: You should follow the guidelines at https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages.
Requesting support: There are a multitude of ways you can get help using Ubuntu, such as the Launchpad answer tracker, the Ask Ubuntu site, the Ubuntu forums, the #ubuntu channel on the https://help.ubuntu.com/community/InternetRelayChat server, and the ubuntu-users mailing list.
Discussing features, existing policy, proposing features, or ideas: This belongs to the ubuntu-devel-discuss mailing list.
Filing a bug against a package not provided by the default, supported Ubuntu repositories: This is due to how it wasn't confirmed by Ubuntu Developers for your release. Problems that unsupported software have caused are upgrade issues, and the program or operating system not functioning correctly. Typically, what isn't supported is software from a PPA (Personal Package Archive), 3rd party packages, self-compiled software, etc. For more on supported Ubuntu repositories, please see here. If you are using unsupported software, it is best to contact the maintainers directly. Instructions are generally available on the program maintainer's web site.
Perform a survey of your problem
If you want to file a translation or misspelling bug, follow the instructions here.
Reporting a crash
If an application crashes, what typically happens is Apport will display a window noting it is collecting information about the crash:
Once done, it will ask you if you would like to report it.
Before continuing, make sure the package whoopsie is installed. Otherwise, Apport will appear to upload a crash report, but only actually does so if whoopsie is installed. Whoopsie is installed by default for users of ubuntu-desktop, but for users of alternative desktops, or for server users, whoopsie has to be installed manually with apt-get install whoopsie. See bug #1001630 for details.
If the crash is in Xorg edit /etc/gdm3/custom.conf from:
# Additionally lets the X server dump core if it crashes #Enable=true
# Additionally lets the X server dump core if it crashes Enable=true
Once you report the crash, what happens next is dependent on what release you are using.
Reporting crash in the development release
What happens next is a web browser opens requesting you to login, and subsequently create a bug report on Launchpad. This report is automatically processed by Apport Retracing Service, in order to provide developers with debugging information that makes it easier to fix the problem.
Reporting a crash in the stable release
If you have a need to file a report on Launchpad anyways (e.g. you don't have access to the errors infrastructure, you want to subscribe others to a report to review it, etc.) one may do so by editing:
'problem_types': ['Bug', 'Package'],
# 'problem_types': ['Bug', 'Package'],
Save, close, and file the crash report via:
Where FILENAME is the file name of the crash file you want to report.
Reporting a crash when no message shows up and crash files created
Sometimes, Apport creates a crash file, but doesn't display a message asking to make a report about it. In this case, one may file a crash report via a terminal:
Where FILENAME is the file name of the crash file you want to report.
To confirm it was reported successfully to Ubuntu's Error Tracker, one may gather the ID via:
sudo cat /var/lib/whoopsie/whoopsie-id
and then go to the following URL with ID replaced with that gathered in the previous terminal command:
Reporting a crash when no message shows up and crash files not created
Sometimes, Apport doesn't create crash files after a crash. If this is due to Apport being disabled one may edit the file:
If Apport is enabled, then you may have one of the following issues:
For system crashes (e.g. system locks up, freezes, logs you out, etc.) one my gather debugging information about system crashes.
For application crashes (e.g. GUI application crash) one will have to manually capture the crash details following this article.
Reporting non-crash hardware and desktop application bugs
The method for reporting bugs in Ubuntu is by using the tool “ubuntu-bug”, otherwise known as Apport. When reporting a bug, you must tell Apport which program or package is at fault.
Collecting information from a specific package
Press Alt+F2 to open the “Run Command” screen:
Then, type ubuntu-bug <package name> and press Enter. If you’re not sure which package has the problem, refer to the instructions for finding the right package.
Collecting information about a program with a window open
If you want to file a bug about an application but you don't know what that application's package name is, if it has an open window you are in luck.
In a terminal execute the command 'ubuntu-bug -w'.
After you close the dialog the next window that you click on will have a problem report created for the package that created the window.
Collecting information from a currently running program
To file a bug against a program that is currently running, open the System Monitor application and find the ID of the process.
Then type "ubuntu-bug " followed by the process ID into the “Run Command” screen.
Filing a general bug against no particular package
First, please review potential package candidates here. Only after reviewing this, if are still not sure which package is affected by the bug, type ubuntu-bug in the “Run Command” screen and press Enter. This will guide you through a series of questions to gather more information about the bug and help you assign it to the appropriate package.
Complete the bug report filing process
After running one of the above commands, Apport (the Ubuntu bug reporter) will gather information about the bug.
A window will then pop up, asking you if you want to report the bug. Click "Send Report" if you wish to proceed, or click "Content of the report" if you want to review the information Apport collected.
Apport will then upload the problem information to Launchpad, and a new browser window will then open to inform you that the bug report is being processed.
After the bug report data has been processed, a new page will open that will ask you for the bug report's title. The bug title will appear in all bug listings so make sure it represents the bug well. When you're done, click "Next".
A search will then occur based on the title you gave to the bug report, and will show potentially similar ones. If one of these seems to be the exact bug you're reporting, click its title, then "Yes, this is the bug I'm trying to report". If not, click "No, I need to report a new bug".
Launchpad will then ask you for further information. It's important that you specify three things:
- What you expected to happen
- What actually happened
- If possible, a minimal series of steps necessary to make it happen, where step 1 is "start the program"
Fill in the description field with as much information as you can, it is better to have too much information in the description than not enough.
At then bottom of the page, there are some extra options you can use to make your bug report more complete:
This bug is a security vulnerability: Please check this only if your bug report describes a behaviour that could be exploited to compromise your security or safety, as well as cause issues such as identity theft or "hi-jacking".
Tags: You can add here tags that pertain to your bug report. The predefined values should be left alone.
Include an attachment: Using this option, you can add supporting attachments to explain or help others reproduce the bug. This might include a screenshot, a video capture of the problem or a sample document that triggers the fault. If necessary, additional attachments can be added after the bug is reported via Add a comment/attachment at the bottom of the page. Please check https://wiki.ubuntu.com/DebuggingProcedures for any further information to provide. It is vital for developers to get this information, as it contains the minimum requirement information necessary for a developer to begin working on your bug.
Please note that if one files a bug against the linux kernel package, you do not need to add as an attachment the terminal command:
lspci -vvnn lspci -vnvn
This is due to how Launchpad automatically generates this as an additional attachment.
When you're done, click "Submit bug report".
Tips and tricks
Filing bugs when offline or using a headless setup
In the event that you have an issue with your internet connection, want to file a bug for another system, or have trouble reporting from a headless setup, you can still do this using apport.
For a bug report about a crash, copy over the .crash file created in the /var/crash folder to the new computer. Then report it from the new computer via a terminal:
For a bug report about any other issue, from the computer with the problem execute the following at a terminal:
apport-cli -f -p PACKAGENAME --save FILENAME.apport
Copy this over to the new computer. If filing a new report, execute via a terminal:
Please do not attach the .apport or .crash file to the report, as this is not the same as performing the above mentioned steps.
Filing bugs manually at Launchpad.net
Before you proceed, you should think about the nature of the problem you're facing. If Ubuntu or its software seems to simply be generally "misbehaving", it might not be a software bug, but it is still a problem we want to help fix. We have an entire community of people who can help you in real time on our live IRC chat channels. You can find a list of these channels at https://wiki.ubuntu.com/IRC/ChannelList. On the other hand, if you are absolutely sure that you've encountered a legitimate error in the software's behavior (especially one that can be reproduced regularly), and you're sure you don't need any help, then continue with the bug reporting process.
If for some reason you cannot file a bug using the Apport tool you can file one via Launchpad's own bug report form. When doing so it is best if you have determined which package it should be filed against. Read 'finding the right package' for guidance or use Launchpad's package search feature. We don't recommend this method for most bug reports because they will likely be missing crucial information, use ubuntu-bug if you can!
To file a bug against a specific package you can also use a URL like the following:
where PACKAGENAME is the name of the source package about which you want to file the bug report.
In the event that you want to request a piece of software be packaged for Ubuntu please follow the instructions in the wiki.
Error: The launchpadlib Python module is not installed
If one gets the following error while trying to perform apport-collect:
ERROR: The launchpadlib Python module is not installed. This functionality is not available.
please install the following package:
sudo apt-get -y install python-launchpadlib
Package libreoffice not installed and no hook available, ignoring
If one attempts to apport-collect and gets the error message:
Package libreoffice not installed and no hook available, ignoring
one has to install the following package:
sudo apt-get -y install libreoffice
Non-crash userspace bugs
Sometimes it is useful to take a picture (with a camera or via PrtSc button), or screencast of the problem to demonstrate how you reproduced it, what the bug specifically shows, and the impact it has.
Filing a translation bug
You should file a translation bug if you are experiencing one of the following issues:
- Wrong translations or spelling mistakes for languages other than English in applications
- Errors in spellcheckers or language support
A string from an application not available for translation in Launchpad Translations
An application from the Ubuntu main repository not available for translation in Launchpad Translations
A translation made in Launchpad Translations and not updated in the Ubuntu language packs
A duplicate translation template (the same application can be translated in two different places) in Launchpad Translations
A template/translation no longer used in Ubuntu and that should be disabled from Launchpad Translations
In case of doubt, you can always contact the Translations team.
All translation issues should be filed against the Ubuntu Translations project. From there the bugs will be triaged and assigned to the right person and package.
Bug reporting etiquette
Following bug reporting etiquette best presents your Launchpad report so that it gets addressed as soon as possible. As well, it minimizes unnecessary pain points for developers, triagers, and original reporters.
All bug reports
Please do not file bug reports about End-of-Life operating systems.
This includes release of Ubuntu, and alternative operating systems. Expecting Ubuntu to provide interoperability with an insecure, end-of-life operating system is simply irresponsible, and inconsiderate of the finite resources of the Ubuntu Community. Information regarding supported Ubuntu releases are available here. Please see the website of the vendor of the operating system for EOL and support information.
Please do not speculate on what you think is or isn't a duplicate report
The exception to this is you are a developer, know specifically where in the code the problem is, and would be submitting a patch to fix the issue. However, noting things like, "I checked Google and found bug report number...", "Why should I file a new report when this is a duplicate?" is largely unhelpful as it tends not to be a duplicate, and already has been or easily done by triagers and developers. Instead, if you are the original reporter, ensuring the report has all the requested testing information performed would be the fastest way to ensure your bug is resolved as soon as possible. If you are not the original reporter, it's best to file a new report, so that necessary debugging attachments are reviewed. It is a common misconception that filing what one initially believes to be a potential duplicate report is not helpful. Filing a new report is quite helpful, and is preferred to ease triaging and development.
Please do not quote Wikipedia and other non-primary resource information as fact on Launchpad.
Please do not complain because someone sent what one perceives to be a automated or "canned" response.
If the response is asking you to do something that you haven't done (ex. test the latest development release, file a new report, etc.) do it, as it would get you closer to having your bug fixed faster. Complaining about this is inconsiderate of the Ubuntu triagers and developers who are saving time in comparison to hand typing every single character in an e-mail that goes out their inbox.
Please test the latest version of the package that is considered responsible for the problem.
For bugs in the Linux (Ubuntu) package, unless the upstream maintainer or kernel developer notes otherwise, if a new mainline kernel comes out, and you haven't tested with it, you run the strong risk of it not being attended to upstream.
Please do not post comments such as “Me too!”, “+1”, “bump”, “same here”, etc., as it is largely unhelpful, produces spammy e-mail traffic to everyone subscribed to the report, and quite often turns out not to be the same root cause.
Please do not post URLs of logs.
For example, links to pastebin.com, paste.ubuntu.com, dropbox.com, etc. If a triager or developer asks you for some information on reproducing or testing, please do not make them dumpster dive by just posting a URL, or saying you already did something in some other report. Instead, put the full reproduction or testing results into the report itself, uncompressed and untarred.
Please do not stack multiple issues into one report.
For example, jamming suspend and hibernate into one report, reporting multiple hotkey problems into one report (ex. Fn+F3 doesn't turn off my laptop WiFi, Fn+Right doesn't turn the brightness on my backlight down, my brightness settings are not remembered after reboot, etc.). Please make one report for each individual problem.
Please do not complain about how long it takes to fix a bug.
This goes along with saying things like severity of your bug is high so it should be fixed immediately, “I cannot believe it’s not fixed…”, XYZ person(s) do not care about fixing bugs, etc. Especially, if you have not followed the directions mentioned in this article, let alone contributed code upstream. This type of behavior is nonconstructive, irritating to others who read your e-mail, and spammy. We all want to see every bug fixed as soon as possible! Naturally, bugs being fixed is limited to reproducibility and clarity of the bug report, the actual impact the bug has on the community, and available developer resources.
Please keep the bug report as objective as possible.
It is desired for you to provide a fact based, technical impact statement on you, your environment, and the potential or actual impact on the community at large.
Please provide all relevant information from https://wiki.ubuntu.com/DebuggingProcedures when you first report your bug.
This is one of the top reasons why bugs do not get marked Triaged, as the minimum requirements for triaging, and dealing with the problem by a developer are not provided.
Please avoid arguing with triagers and developers.
If a triager or developer asks you to provide information, just provide the information as requested. An example of this is claiming exemption because you or someone else filed a bug report upstream or downstream (which is publicly viewable, and has no restrictions on who can file). You are being asked for this information so that it would provide more information on how to fix the problem. Also, not everyone has access to the hardware you are reporting against, or reproduce the problem as advised in the report. Having you provide the information helps eliminate the difficulty in fixing your bug. If you have a strong disagreement with what a triager or developer is asking of you, please resolve it with them directly via personal message, not on the bug report. This avoids turning a bug development report into a “let’s talk about talking about the problem” tangent, distracting from having your bug solved. The Ubuntu community takes a favor to objective, technical discourse.
Please do not add project tasks to bug reports that are invalid because they are not supported.
For example, if you were using the an application or package from a PPA that is also housed in a supported Ubuntu repository, reported a bug against the software on Launchpad as PACKAGE (Ubuntu), where PACKAGE is the name of the software, please do not add a Launchpad Project to the report, or change the PACKAGE (Ubuntu) to an upstream project task. The purposes of adding the upstream project to a report is to track valid bugs in Ubuntu that are valid upstream, and may have been reported upstream, not to start another upstream bug tracker.
Many of the triagers and developers who are providing support to you, are volunteers doing so out of altruism. Please keep this in mind when making your comments.
Please do not compress/tar attachments when posting them to a bug report.
Launchpad doesn't have the same attachment size restriction as other bug reporting platforms. Hence, one may attach large files without fear of rejection. While it is appreciated that one is being considerate and efficient regarding reducing network bandwidth traffic, and storage requirements, this is counteracted by hindering the speed with which a triager or developer may begin analyzing the logs you provide.
Please test the latest version of the software from upstream.
Testing the latest upstream release helps in finding out if the issue is a downstream (Ubuntu) issue, or an upstream one as well. If an upstream, then they may also be engaged in seeking support for the problem.
Please check to see if you problem is a regression.
If your bug is a regression, it is most helpful to have it bisected. If it is a linux kernel issue, one would consult the article on bisection. Report your bisect results in the report.
Please do not run apport-collect more than once per release tested.
For example, if you originally reported a bug in an earlier release via Apport, and then could reproduce it a later release, only run apport-collect once in the earlier release. This minimizes unnecessary email traffic to those subscribed to your report and keeps the report efficient.
Please do not change the Status of reports confirmed to be Fix Released.
For example, a bug was reported against version 1 of the software. Version 2 comes out and is confirmed fixed by the original reporter. However, version 3 comes out later, and either the same or different problem occurs. Instead of reopening the report about version 3 causing a new problem, please file a new report. This allows the focus to be on how the issue was a regression going from version 2 to 3, and doesn't carry over the baggage from the old report into the new one.
Hardware bug reports (linux kernel, xorg, sound, etc.)
Before filing your report, please update your buggy and outdated BIOS, and hardware firmware (CF card readers, SSDs, USB 3.0 controllers, DVD/CD drives, external USB drives, etc.) to the newest available from your vendor.
Outdated and buggy BIOS and firmware is a common cause of a variety of issues. For example, freezing after lightDM login, intermittent wireless, suspend/hibernate not working, intermittent touchpad, certain keys on keyboard not working correctly, card readers not working, and kernel panics after plugging USB drive in (this is by no means an exhaustive list). In addition, BIOS updates are for collateral damage avoidance. For more on this, please see here.
One report, per person, per hardware combination, per bug.
Many Linux package, hardware, and other non-user space bugs are hardware dependent on both the hardware itself, and what other hardware the problematic hardware is connected to. For more on this please see here, and further below in this article.
Please do not post comments to another persons report, claiming you have the same or similar hardware or problem.
Instead, please file a separate report, and make comments there. This is because no one can verify if you would have the same problem or not, because your hardware can not be analyzed. Also, vendors can have different parts under the hood of the same model line.
Please do not attempt to apport-collect to another persons report.
Running apport-collect when not specifically asked by a triager or developer creates spammy E-Mail traffic for those subscribed, clutters up the bug report with undesired attachments, and hinders the bug getting addressed quickly. As well, your attachments are subject to immediate deletion at the discretion of developers and triagers. Instead, please open a new report via ubuntu-bug. Please note that attempting to run apport-collect bug_number against a linux package bug report, while booted into a mainline linux kernel will not work. This is due to how Ubuntu does not provide support for mainline kernels. For more on this, please see here.
Please do not solicit non-original reporters to post comments, attachments, etc.
Please do not attach anything to another persons report.
Adding undesired attachments when not asked by a triager or developer creates spammy E-Mail traffic for those subscribed, clutters up the bug report with undesired attachments, and hinders the bug getting addressed quickly. As well, your attachments are subject to deletion at the discretion of developers and triagers.
Still have doubts about the bug report filing process? You can ask someone on #ubuntu-bugs on the https://help.ubuntu.com/community/InternetRelayChat server or on the bugsquad mailing list.