How to Write a Bug Report That Gets Fixed
Learn how to write clear, actionable bug reports in English that developers can act on immediately — with templates, real examples, and common mistakes to avoid.
A bug report is a communication document. Its purpose is not just to record that something is wrong — it is to give another person enough information to reproduce the problem, understand the impact, and fix it efficiently. Poor bug reports create back-and-forth conversations, waste developer time, and sometimes result in the bug being closed as “cannot reproduce.” Good bug reports get prioritised and resolved.
Why Most Bug Reports Fail
The most common reasons bug reports get ignored or deprioritised:
- Too vague: “The app crashes sometimes” tells a developer almost nothing they can act on.
- Missing reproduction steps: Without knowing how to trigger the bug, engineers cannot confirm it exists or test a fix.
- No expected vs. actual behaviour: Without knowing what should happen, it is impossible to verify that a fix is correct.
- Wrong severity assessment: Over-stating severity causes noise; under-stating it causes important bugs to be missed.
- Buried in prose: A wall of text makes it harder to extract the key information quickly.
Key Vocabulary
- Reproduction steps (also: steps to reproduce, STR) — the exact sequence of actions needed to trigger the bug
- Expected behaviour — what the system should do according to the specification or intuition
- Actual behaviour — what the system actually does when the bug occurs
- Severity — the impact of the bug on the system or user (Critical, High, Medium, Low)
- Priority — how urgently the bug should be fixed, often set by the product owner
- Environment — the context in which the bug occurs (OS, browser, device, build version)
- Regression — a bug that was previously fixed but has reappeared
- Intermittent — a bug that does not occur consistently, making it harder to reproduce
- Blocker — a critical bug that prevents a user from completing an essential action
- Workaround — an alternative approach that lets the user achieve their goal despite the bug
The Standard Bug Report Structure
A well-written bug report follows a consistent structure. Every field has a purpose.
Title
The title should be specific and searchable. It should describe the problem, not the symptom in vague terms.
| Weak title | Strong title |
|---|---|
| Login broken | Login button unresponsive after password reset on iOS 17.4 |
| App crashes | App crashes when uploading image larger than 5MB on Android |
| Search doesn’t work | Search returns no results for queries containing apostrophes |
The formula is: [Component] [what goes wrong] [when/where/condition]
Description
The description provides context. Include:
- A one-to-two sentence summary of what is wrong
- When the issue was first noticed (especially for regressions)
- How frequently it occurs (always, intermittently, only under certain conditions)
Example: “The password reset flow does not redirect the user to the login page after they set a new password. Instead, the page reloads and shows the same form with a blank password field. This behaviour occurs consistently on iOS devices running Safari. First observed in build 4.2.1.”
Steps to Reproduce
This is the most critical section. Number your steps clearly. Be precise about which element you click, what data you enter, and what order events happen in.
Example:
- Open the app on an iPhone 14 running iOS 17.4 and Safari 17.
- Tap “Forgot your password?” on the login screen.
- Enter a registered email address and tap “Send reset link.”
- Open the email and tap the reset link.
- Enter a new password and tap “Set new password.”
- Observe the page behaviour.
Expected Behaviour
State what should happen in plain, direct English.
“After tapping ‘Set new password’, the user should be redirected to the login screen with a confirmation message: ‘Your password has been updated. Please log in.’”
Actual Behaviour
State exactly what happens instead.
“The page reloads and displays the password reset form again with both password fields empty. No confirmation message is shown. The new password has been saved (the user can log in manually), but the redirect does not occur.”
Environment
Include all relevant technical context:
- OS: iOS 17.4
- Browser/App version: Safari 17, App v4.2.1
- Device: iPhone 14 Pro
- Account type: Standard user (issue not reproduced on admin accounts)
- Network: WiFi and cellular (both affected)
Severity and Priority
Severity: High — The user cannot complete the flow without confusion. They may believe the password reset failed.
Priority: High — This affects the primary authentication recovery path.
Attachments
Always include:
- A screenshot showing the actual behaviour
- A screen recording if the bug is time-sensitive or involves a sequence of events
- Console logs or error messages if accessible
- A HAR file (network recording) for API-related bugs
Writing for an International Team
When writing bug reports for a global team, clarity is more important than eloquence. Use simple, direct sentences. Avoid idioms, sarcasm, or ambiguity.
Less clear: “The search seems to have gone haywire when I threw some special characters at it.”
More clear: “The search feature returns an error page (500) when the query contains the characters & or %.”
Use the active voice to describe both the user’s action and the system’s response:
- “The user taps ‘Submit’” (not “Submit is tapped by the user”)
- “The system displays a 404 error” (not “A 404 error is displayed”)
A Template to Copy and Use
**Title:** [Component] [problem] [condition]
**Description:**
[1-2 sentences explaining the problem and context]
**Steps to Reproduce:**
1.
2.
3.
**Expected Behaviour:**
[What should happen]
**Actual Behaviour:**
[What actually happens]
**Environment:**
- OS:
- Browser/App version:
- Device:
**Severity:** Critical / High / Medium / Low
**Frequency:** Always / Intermittent / Rare
**Attachments:**
[Screenshot / Video / Logs]A well-written bug report is an act of respect for the engineers who will investigate it. It saves time, reduces frustration, and signals professional competence. The effort you invest in writing clearly is repaid many times over in faster, more accurate fixes.