Reporting issues — The Linux Kernel documentation

Working with the development community
Internal API manuals
Development tools and processes
User-oriented documentation
Firmware-related documentation
Architecture-specific documentation
Are you facing a regression with vanilla kernels from the same stable or longterm series? One still supported? Then search the LKML and the Linux stable mailing list archives for matching reports to join. If you don’t find any, install the latest release from that series. If it still shows the issue, report it to the stable mailing list (stable@vger.kernel.org) and CC the regressions list (regressions@lists.linux.dev); ideally also CC the maintainer and the mailing list for the subsystem in question.
In all other cases try your best guess which kernel part might be causing the issue. Check the MAINTAINERS file for how its developers expect to be told about problems, which most of the time will be by email with a mailing list in CC. Check the destination’s archives for matching reports; search the LKML and the web, too. If you don’t find any to join, install the latest mainline kernel. If the issue is present there, send a report.
The issue was fixed there, but you would like to see it resolved in a still supported stable or longterm series as well? Then install its latest release. If it shows the problem, search for the change that fixed it in mainline and check if backporting is in the works or was discarded; if it’s neither, ask those who handled the change for it.
General remarks: When installing and testing a kernel as outlined above, ensure it’s vanilla (IOW: not patched and not using add-on modules). Also make sure it’s built and running in a healthy environment and not already tainted before the issue occurs.
If you are facing multiple issues with the Linux kernel at once, report each separately. While writing your report, include all information relevant to the issue, like the kernel and the distro used. In case of a regression, CC the regressions mailing list (regressions@lists.linux.dev) to your report. Also try to pinpoint the culprit with a bisection; if you succeed, include its commit-id and CC everyone in the sign-off-by chain.
Once the report is out, answer any questions that come up and help where you can. That includes keeping the ball rolling by occasionally retesting with newer releases and sending a status update afterwards.
The above TL;DR outlines roughly how to report issues to the Linux kernel developers. It might be all that’s needed for people already familiar with reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For everyone else there is this section. It is more detailed and uses a step-by-step approach. It still tries to be brief for readability and leaves out a lot of details; those are described below the step-by-step guide in a reference section, which explains each of the steps in more detail.
Note: this section covers a few more aspects than the TL;DR and does things in a slightly different order. That’s in your interest, to make sure you notice early if an issue that looks like a Linux kernel problem is actually caused by something else. These steps thus help to ensure the time you invest in this process won’t feel wasted in the end:
Are you facing an issue with a Linux kernel a hardware or software vendor provided? Then in almost all cases you are better off to stop reading this document and reporting the issue to your vendor instead, unless you are willing to install the latest Linux version yourself. Be aware the latter will often be needed anyway to hunt down and fix issues.
Perform a rough search for existing reports with your favorite internet search engine; additionally, check the archives of the Linux Kernel Mailing List (LKML). If you find matching reports, join the discussion instead of sending a new one.
See if the issue you are dealing with qualifies as regression, security issue, or a really severe problem: those are ‘issues of high priority’ that need special handling in some steps that are about to follow.
Make sure it’s not the kernel’s surroundings that are causing the issue you face.
Create a fresh backup and put system repair and restore tools at hand.
Ensure your system does not enhance its kernels by building additional kernel modules on-the-fly, which solutions like DKMS might be doing locally without your knowledge.
Check if your kernel was ‘tainted’ when the issue occurred, as the event that made the kernel set this flag might be causing the issue you face.
Write down coarsely how to reproduce the issue. If you deal with multiple issues at once, create separate notes for each of them and make sure they work independently on a freshly booted system. That’s needed, as each issue needs to get reported to the kernel developers separately, unless they are strongly entangled.
If you are facing a regression within a stable or longterm version line (say something broke when updating from 5.10.4 to 5.10.5), scroll down to ‘Dealing with regressions within a stable and longterm kernel line’.
Locate the driver or kernel subsystem that seems to be causing the issue. Find out how and where its developers expect reports. Note: most of the time this won’t be bugzilla.kernel.org, as issues typically need to be sent by mail to a maintainer and a public mailing list.
Search the archives of the bug tracker or mailing list in question thoroughly for reports that might match your issue. If you find anything, join the discussion instead of sending a new report.
After these preparations you’ll now enter the main part:
Unless you are already running the latest ‘mainline’ Linux kernel, better go and install it for the reporting process. Testing and reporting with the latest ‘stable’ Linux can be an acceptable alternative in some situations; during the merge window that actually might be even the best approach, but in that development phase it can be an even better idea to suspend your efforts for a few days anyway. Whatever version you choose, ideal