How to Write a Bug Report That Actually Gets Fixed

Separate what you did from what you concluded

The most common failure in a bug report is that observation and diagnosis are mixed together. "The save button is broken" is a conclusion. It may be right, but it tells the reader nothing about how to see it, and if it is wrong it sends them somewhere the bug is not.

Report what you did, what you expected, and what happened instead — in that order, and without interpretation. If you do have a theory, put it at the end under its own heading, clearly flagged as a theory. Good engineers want your hypothesis; they just need it kept separate from your evidence.

This matters more than it sounds. A confidently worded wrong diagnosis routinely costs more time than no diagnosis at all, because it anchors the investigation before it has started.

The five things every report needs

A report is complete when someone who has never seen the problem can reproduce it without asking you anything. In practice that means five elements:

• Numbered steps starting from a known state — begin at a URL or a login, not "from the dashboard".
• Expected result, stated as one sentence.
• Actual result, stated as one sentence, including the exact error text rather than a paraphrase.
• Environment — browser and version, operating system, device, and the build or release you saw it on.
• Frequency — every time, or one in five, and whether it survives a page reload.

Frequency is the field people skip and shouldn't

An intermittent bug and a consistent one are different problems requiring different approaches, and knowing which you have changes where an engineer starts looking. A consistent failure is usually a logic error and is often quick to find. An intermittent one usually involves timing, caching, or state left behind from something earlier — and hunting that as though it were deterministic wastes hours.

So say so explicitly. "Happened three times out of about ten attempts, always after leaving the tab open for a few minutes" is worth more than a paragraph of description, because it points directly at a category of cause.

Attach the evidence that survives the retelling

A screenshot showing the error and the surrounding context is worth more than a description of it, because it captures details you did not think to mention. A short screen recording is worth more still for anything involving timing or a sequence of interactions.

For anything in a browser, open the developer console and include what is in it. A red error message there frequently identifies the failing code directly and converts a day of investigation into a few minutes. Include the network tab too if the problem involves loading or saving — a failed request with its status code is often the entire answer.

Paste text as text, not as a screenshot of text. Engineers search error messages; they cannot search a picture.

Severity is about impact, not annoyance

Severity ratings drift upward when everyone rates their own bug by how much it irritated them. The result is a backlog where everything is critical and nothing is prioritised, which helps nobody — least of all the person whose bug genuinely is critical.

Rate by consequence instead: how many users are affected, whether there is a workaround, and whether anything is lost or corrupted. A cosmetic misalignment on a page every user sees may well matter more than a crash in a feature three people use, and stating your reasoning briefly lets the triager disagree with the reasoning rather than with you.

Using a consistent template for all of this is what makes it habitual rather than an effort of will each time — and a report written to a template takes less time to write, not more, because you stop deciding what to include.

Reporting something you cannot reproduce

Sometimes you genuinely cannot make it happen again, and the temptation is to say nothing rather than file something incomplete. That is usually the wrong call — a report of a real failure with partial detail is more useful than silence, provided you are explicit about the uncertainty.

Write down everything you can still recall while it is fresh: roughly what time it happened, what you were doing immediately before, whether anything was unusual about that session, and any identifier visible on the screen such as an order or reference number. Those identifiers are the most valuable thing in the report, because they let someone find the exact request in the logs and see what the system saw.

Then say plainly that you could not reproduce it and describe what you tried. That sentence prevents an engineer from spending an afternoon assuming it is deterministic, and it turns an apparently vague report into a specific, honest one. A bug that happens rarely is still a bug, and the ones that are hardest to reproduce are often the ones worth finding.

Tools mentioned in this guide