13
steps before you send
Embedded Linux on Edge-AI 23rd Sept 2026 enrollingLinux kernel & Device drivers starts on 24th Oct 2026 enrollingCorporate on-site training - Submit proposal Pick your modulesSharpen your kernel skills: deep dives, drivers, Yocto, CVEs, careers — updated daily. Read the blog →Embedded Linux fast track starts 23rd sept 2026 enrollingEmbedded Linux Mastery track starts 23rd sept 2026 enrollingLinux systems engineering starts 23rd sept 2026 enrolling
Free resource
From a fault you found to a report a maintainer acts on
The order to work in before you send a fault upstream, and the check that proves each step. Written for an engineer who knows the code but has never sent a report to a kernel mailing list.
Get the printable PDF1-5
business days to a reply
Proof
at every step
Read this first
One decision comes before the checklist
If the fault has security consequences, stop. It does not go to a public mailing list, and it cannot be recalled once it is sent. Report it privately to the kernel security team at security@kernel.org, in plain text with no attachments, and state the affected kernel version range. Reports without a version range are not processed. Everything below assumes an ordinary, non-security fault.
There is no central bug tracker for the Linux kernel. A report is mail to a named maintainer and a public list, competing with everything else in that inbox. That is why preparation, rather than the difficulty of the bug, usually decides whether anyone replies.
Steps 01-03
Decide where this goes
The three questions that determine the whole route. Answering them last is the most common way a report reaches the wrong people.
STEP 01
Rule the fault in or out as a security issue
This is first because it is the only step that cannot be corrected later. Once a fault with security consequences is on a public archive, the disclosure has happened.
- Ask whether the fault lets an unprivileged process gain privilege, read memory it should not, or crash the machine from user space.
- If any of those are plausible, use the private route and do not continue down this page.
- If you are unsure, treat it as security and ask privately. The cost of asking is a reply; the cost of guessing wrong is a disclosure.
- Prepare the affected version range before you write, because a report without one is not processed.
Proof it worked: A one-line written answer, in your own notes, saying which route this fault takes and why.
Where this goes wrong: The reflex is to post to the subsystem list and let the maintainers decide. That decision is not theirs to make after the fact, because the archive is already public and indexed.
STEP 02
Establish whose kernel this actually is
Upstream developers cannot fix code they did not write. A vendor kernel carries patches that exist nowhere upstream, so a report against it usually cannot be acted on.
- Record the exact kernel with
cat /proc/version, and check whether it came from a vendor, a distribution or kernel.org. - If it is a vendor or board-support kernel, the report goes to the vendor unless you can reproduce the fault on a vanilla kernel.
- Note that a support contract with a vendor does not entitle you to fixes from upstream developers.
- Decide, and write down, which of the two reports you are preparing.
Proof it worked: A named tree and version you can point at, and a stated decision to report to the vendor or upstream.
Where this goes wrong: Distribution kernels vary. Some ship close to mainline, and some carry years of patches. The test is not the vendor name but whether the fault survives on a vanilla build.
STEP 03
Establish whether this is a regression
A regression is something that worked on one kernel and works worse or not at all on a newer one built with a similar configuration. Regressions carry more weight and follow a different route, so decide now rather than later.
- Find a kernel version where the behaviour was correct, and one where it is not.
- Build the newer version with
make olddefconfigfrom the working configuration, so a configuration difference is not mistaken for a code regression. - Remember the rule covers interfaces the kernel provides to user space. Breakage of kernel-internal interfaces used by out-of-tree modules does not qualify.
- A slowdown counts only if it is significant: five percent in a micro-benchmark is not enough unless a broad benchmark also moves by more than one percent.
Proof it worked: Two version numbers: one that works and one that does not, tested with configurations that match.
Where this goes wrong: Comparing a distribution kernel against a self-built one is not a regression test. The configurations differ in hundreds of places, and any of them could explain the change.
Steps 04-06
Make it reproducible upstream
STEP 04
Reproduce on a kernel upstream can still fix
The report has to be against code the maintainers are still working on, or there is nothing for them to change.
- Install a mainline kernel. The kernel.org front page usually shows mainline as a release candidate, and that is the one to use, because fixes must be applied there first.
- Do not avoid a release candidate because of the letters rc. It is where the work happens.
- Use a vanilla build: sources taken straight from kernel.org, not modified or enhanced.
- The latest stable release is acceptable in some situations and is the better choice during a merge window. Longterm kernels are too far from current code for a first report.
Proof it worked: The same fault, on a vanilla mainline kernel you built or installed yourself, reproduced at least twice.
Where this goes wrong: A fault that reproduces once and never again is usually not reportable. It may be a single bit flip, and a maintainer has no way to act on an event that cannot be repeated.
The full version of every stage is in the PDF
Stages 01 to 03 above are complete. Enter your email and we send the full 13-stage checklist, laid out to print.
No mailing list, no spam. By email we send the file once and stop.
STEP 05
Prove the kernel is not tainted
The taint flag records that something has already happened which can produce unrelated follow-up errors. A maintainer cannot separate your fault from that noise, so tainted reports are frequently set aside.
- Read
cat /proc/sys/kernel/tainted. Zero means clean; any other value is a bitfield of reasons. - Decode a non-zero value with the script
tools/debugging/kernel-chktaint, shipped by many distributions in a linux-tools or kernel-tools package. - In a crash log, the state is on the line starting with
CPU:, after the process id and command name. - Disable DKMS and akmods first, because they rebuild external modules automatically and re-taint the kernel on the next boot.
Proof it worked: A value of zero on the freshly installed kernel, checked after a reboot rather than before.
Where this goes wrong: Taint stays set after you unload whatever caused it, so an
rmmod does not clear it. Only a reboot does. Checking the flag on the old kernel and assuming the new one inherits the result is the usual mistake.STEP 06
Reduce the reproduction
The shorter the path to the fault, the more likely someone can run it on their own hardware. This is the step that converts a report into something testable.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →Steps 07-09
Make the evidence readable
STEP 07
Decode the failure instead of pasting it
A trace full of hexadecimal offsets is work you are asking the maintainer to do, using a build only you have.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →STEP 08
Collect the facts every report must carry
These are the details a maintainer needs before they can even classify the report, and asking for them costs a round trip of several days.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →STEP 09
Clear the logs for publication
This step exists because the board is often not yours. A kernel log is a permanent public document once it reaches an archive.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →Steps 10-13
Send it, and stay with it
STEP 10
Find the maintainers and the lists
A report has no default destination. This step decides whether anyone reads it.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →STEP 11
Write it from evidence to subject
Developers skim. The subject, the first sentence and the first paragraph decide whether the rest is read, which is why they are written last.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →STEP 12
Add the regression route, if step 03 said so
Regressions are tracked separately and treated with more urgency, but only if you register them.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →STEP 13
Stay in the conversation
A report is the start of an exchange. Most reports that die after being sent die because the reporter stopped answering, not because the maintainer stopped caring.
4 checks, the proof and the failure modes — in the full checklistEnter your email for the full version →What it leads to
Why this is worth doing carefully
A report on an archived list is permanent and citable. When someone fixes the fault, the kernel process asks them to credit you with a Reported-by: tag and a Closes: tag pointing at the URL of your report, and private trackers are not allowed there. A report filed only in an internal system cannot be referenced by the fix. Over a few years, a set of well-described reports is a public record of problems you found, which is harder to build and harder to fake than a list of technologies.
The debugging that produces a report like this is the same work as debugging a driver that fails during probe. If you want to practise it deliberately, that is what our Linux device drivers training covers.
Take the checklist with you
The complete version, laid out to print and keep. Sent once.
No mailing list, no spam. By email we send the file once and stop.
Questions
Common questions
How do I use this checklist?
Work the steps in order, from 01 to 13, and produce the proof for each step before moving to the next. Step 01 can end the process early: if the fault has security consequences it goes privately to the kernel security team and not to any public list. The printable PDF contains all 13 steps in full, so you can work through it away from the screen.
Do I need to know the subsystem to report a bug in it?
No. You need to describe what you observed accurately and make it reproducible. Analysis is welcome but is not required, and a wrong guess about the cause in an otherwise clear report does no harm.
What if I cannot reproduce the fault on a mainline kernel?
Then the report goes to whoever ships the kernel you are running, which is usually your vendor or distribution. Upstream developers cannot change patches that exist only in someone else’s tree.
Is it worth reporting if I cannot fix it myself?
Yes. Reporting and fixing are separate contributions. A clear report with a reliable reproduction is useful to a maintainer even when it comes with no patch at all.
Is the full checklist free?
The page shows the first steps in full and summarises the rest. The complete printable PDF with all 13 steps is sent by email. We send the file once, and there is no mailing list.
Related tools and resources
Keep going
Read free + printable PDFBoard Bring-Up ChecklistA board that will not boot fails in a predictable order, and days go to debugging the wrong stage. 13 stages with the proof that each one worked.Open →
Read free + printable PDFEmbedded Linux GlossaryBSP, DTB, SBOM - the acronyms that fill docs, forum posts and reviews, decoded. 25 terms with the misunderstanding corrected: a BSP treated as a kernel, an SBOM produced by scanning.Open →
Free guideChoosing Your First SBCWhich board fits what you want to build - learning Linux internals, home automation, vision, robotics. Matched by use case, with the four checks before you buy.Open →
Live once a monthFree monthly masterclassOne free hour, live, every month, with a working kernel engineer. Bring your questions - including the one about how to get into this field. Recordings stay on YouTube.Open →
Free career guideCareer roadmapsWhich skills stay in demand as AI spreads, and the order to learn them - for the embedded Linux and kernel paths.Open →