How to file a bug report developers actually want to fix

A great bug report leads with the title and the steps to reproduce, then layers on evidence — a screenshot or replay, console and network logs, the environment, and an explicit expected-vs-actual pair. Get those six fields right and developers stop bouncing your tickets back with "need more info." Get them wrong and your bug sits in triage limbo while everyone burns time on clarification.

This isn't a matter of taste. The organizations that process the most bug reports on earth converge on the same short list. Mozilla's Bug Writing Guidelines state plainly that steps to reproduce are "the most important part of any bug report" — and that if a developer can reproduce the bug, it is "very likely to be fixed." Atlassian's Jira bug-report guidance calls the numbered reproduction steps "the most vital section." The most-cited essay on the subject, Simon Tatham's How to Report Bugs Effectively, reduces the whole discipline to one sentence: "The aim of a bug report is to enable the programmer to see the program failing in front of them."

Most weak bug reports fail one of three ways:

1. Missing or vague repro steps. A one-liner like "the page broke" with no path to reproduce forces the developer to hunt through your account history before they can even start. If the steps are unclear, Mozilla notes, "it might not even be possible to know whether the bug has been fixed."
2. Wrong altitude. Reports either over-describe ("on Tuesday I clicked the green button while listening to Spotify…") or under-describe ("checkout broken"). Tatham's advice is to separate facts — "I was at the computer and this happened" — from speculation — "I think the problem might be the cache." Leave out speculation if you must; never leave out facts.
3. No evidence. When something is intermittent, race-condition-y, or purely visual, words alone can't convey what the user saw.

The cost is real and it compounds. Ministry of Testing's practitioner community describes teams that "struggle with incomplete bug reports, unclear reproduction steps, and disagreements about bug severity" as a routine tax on delivery. Every ambiguous ticket is a round-trip: the developer asks, the reporter answers a day later, the developer has swapped context twice. Multiply that across a sprint and a QA team's throughput quietly halves.

A good title is the search query your future self would type to find this bug six months from now. It should name the feature, the symptom, and the condition. Bad: "checkout broken." Good: "Stripe Checkout fails with 'card_declined' on prepaid cards over $50." Atlassian recommends a title that reads like [Area] Component fails to do X after Y — for example, "[Browser] Profile picture fails to load after edit" — so it's instantly scannable in a triage queue.

Numbered steps. Starting state explicit. Click targets unambiguous. Expected vs actual stated inline at the failure point. Mozilla's guidance is to give minimized, easy-to-follow steps and to include any special setup the bug requires — and, critically, to check that the steps reproduce in a fresh profile and on more than one machine before filing, so you're reporting a genuine defect and not a corrupted local state. The same discipline applies to any app: reproduce it in an incognito window with no extensions before you claim it's a bug in the product.

The two-line "→ Actual / → Expected" pattern above is the most underrated bug-report convention. It forces you to articulate the intent of the feature, not just the symptom. Google's engineers make the same point from the maintainer's side: expected-behavior information "helps you decide which API is actually broken, where it's broken, and what the expected behavior is." Stating expected behavior explicitly also heads off the most tedious triage outcome — the "this is actually working as designed" disagreement — before it becomes a week of ticket ping-pong.

• Browser + version (Chrome 137, Firefox 128, Safari 18.4)
• OS + version
• App version — commit SHA if available, release tag otherwise
• Device (desktop / mobile / tablet, viewport size for responsive bugs)
• Network conditions (only if relevant)

Atlassian is blunt about why this matters: "some bugs may only be reproducible in specific environments," so documenting the environment lets a developer recreate the exact conditions and isolate the cause. If your capture tool records these automatically — and it should — you can skip filling this section by hand entirely.

• Screenshot for static visual bugs (alignment, contrast, typo). Crop or annotate the region of interest.
• Video / GIF for state changes you can narrate.
• Session replay for race conditions, intermittent failures, or "it works on my machine."

State your perceived severity: "blocks production checkout" versus "minor cosmetic on the settings page." But be precise about what you're claiming. Severity is technical impact — how badly the software is broken. Priority is urgency — the order the team will fix things in. Atlassian's guidance is to rate both, because "not all [bugs] are equally important": a defect that interrupts a crucial function has to be fixed immediately, unlike a small graphical correction. A crash on a rarely used admin screen can be high severity yet low priority; a wrong price on your pricing page can be low severity yet top priority. The triager owns the final priority — but they need your severity signal to set it well.

Nothing teaches the six fields faster than watching a useless report become a great one. Here is a real-shaped bug as it usually arrives:

Every failure mode is here. The title isn't searchable. There are no steps, no environment, no expected-vs-actual, no evidence. "Some users" is unactionable. "Might be a caching thing" is speculation presented as a lead — exactly what Tatham warns against. A developer can do nothing with this except reply "need more info," and now you've lost a day. Now the same bug, filed properly:

The second report is a work order. It names the exact condition (prepaid cards over $50), proves reproducibility (5/5, two machines — the check Mozilla asks for), pins the environment to a build SHA, and hands the developer the smoking gun: a 402 racing a late webhook. Nobody has to ask a follow-up question. That is the entire difference between a bug that ships a fix this afternoon and one that rots in the backlog.

If you optimize one thing, optimize reproducibility. Google's testing team frames the maintainer's reality precisely: bugs that "make fast progress tend to be quick to reproduce with a clear expected behavior," while unreproducible bugs stall because they usually stem from nondeterminism — timing, ordering, uninitialized state, concurrency — that a developer can't recreate on demand. Ministry of Testing makes the consequence explicit: whether a bug can be reproduced consistently is "a key factor affecting whether it gets fixed," and an intermittent bug can be prioritized "so low that it never gets fixed" at all.

This is why the humble reproduction rate — "5/5 attempts" versus "happened once" — carries so much weight. It tells the developer whether they're chasing a deterministic defect or a heisenbug, and it sets their expectation for how much instrumentation they'll need. When you can't reproduce a bug, don't stay silent: Ministry of Testing's advice is to report irreproducible failures anyway, but "with extra care" — label the bug clearly as irreproducible, give a detailed account of exactly what happened, and attach every scrap of evidence (screen recording, console logs, API calls) you captured at the moment it occurred. A single replay of a one-time failure is often the only thing that lets an engineer form a hypothesis at all.

Evidence is where reports either become self-sufficient or stay dependent on you. Aim to attach — or, far better, autocapture — three layers:

• Console. The errors and warnings from the failed session, with stack traces. A single uncaught exception often points straight at the line.
• Network. A HAR or request log for the relevant calls: status codes, payloads, headers, timing. Most "the button did nothing" bugs are a 4xx or 5xx hiding under a silent catch.
• State + replay. A DOM session replay for the failure window, plus any relevant client state (local storage, cookies, store snapshot). This is what turns "it hung for 8 seconds" into a scrubbable timeline you can inspect frame by frame.

The trap with manual evidence is that reporters capture the wrong slice — a screenshot of the error toast, but not the network 402 that caused it. Autocapture removes that judgment call by recording everything around the failure, which is exactly the moat that tools built on rrweb provide.

The six-field discipline is a floor, not a ceiling — and pushed too far it has real failure modes worth naming honestly.

• Over-reporting. Not every observation deserves a ticket. Filing a bug for something you haven't tried to reproduce, or logging five near-identical cosmetic nits as separate P3s, buries the signal your team needs. If you can't reproduce it and have no evidence, that's a note in a channel, not a formal defect.
• Duplicate triage cost. Every large tracker fills with duplicates, and triaging them isn't free. Before filing, search existing issues — Atlassian's own bug-triage guidance treats de-duplication as a first-class triage step. A good duplicate that adds a fresh repro path or environment is useful; a lazy one just adds queue noise.
• Template rigidity. A six-field template is a prompt, not a bureaucratic gate. Don't block someone from reporting a real crash because they didn't fill the "device" field. The goal is a report a developer can act on, and Atlassian's own summary of a good report is that it's "brief but complete" — complete enough to reproduce, brief enough to read.
• Privacy. Rich capture is powerful and dangerous: replays and network logs can contain passwords, tokens, and PII. Never solve reproduction by asking a reporter to DM their credentials. Redact before the data leaves the browser.

Everything above is a discipline you can adopt with a plain text template today. What tooling changes is who has to remember it. When a teammate hits a bug in your app with the BugMojo browser extension (Chrome, Firefox, or Edge) installed, they don't fill out a form — they highlight the broken element, type one sentence, and submit. BugMojo attaches:

• The recent window of DOM mutations as an rrweb session replay
• Every console message during that window
• Every network request — status, payload, headers — with PII redacted client-side, before the data ever leaves the browser
• Browser, OS, viewport, page URL, and build context

Because capture is automatic, the environment section fills itself and the evidence is the right slice by construction — the very failure modes that make manual reports bounce. BugMojo also runs no-setup Quick Capture for one-off bugs, and its MCP integration lets an AI coding agent read the same replay-backed report a human triager would, so a bug can be assigned to a person or an agent from the same ticket.

• Adopt the six fields. Copy the title / steps / expected-vs-actual / environment / evidence / severity structure into your team's template in Linear, Jira, or GitHub Issues. Make it the default.
• Autocapture the environment and logs. Whether it's BugMojo, another rrweb-based tool, or a homegrown extension, removing the manual capture step is the single biggest workflow upgrade a QA team can make.
• Measure the round-trip. Pick a sprint, require the six fields on every bug, and track ticket round-trip time before and after. The reduction in "need more info" replies tells the rest of the story.