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.
Navigating Nuances: Precise Language for International Teams
Writing effective bug reports isn’t just about describing what’s broken; it’s about communicating clearly and precisely enough for your colleagues – especially those learning professional English – to understand the problem and implement a solution. A common hurdle for non-native speakers is using overly vague or informal language, which can lead to misinterpretations and delays in fixing bugs. Let’s look at some specific areas where careful phrasing makes all the difference.
Firstly, replace colloquialisms and idioms with their direct equivalents. Instead of saying “it’s throwing a fit,” which might be understood metaphorically but could confuse someone unfamiliar with that expression, use “the application is encountering an error.” Similarly, avoid phrases like “something’s not working right” – it’s far more precise to state: “The button does not respond when clicked.” This demonstrates attention to detail and avoids ambiguity. Pay particular attention to verbs; “fix” can be replaced with the more formal and descriptive “resolve,” “correct,” or “address.”
Another key area is describing steps to reproduce a bug. A typical request might be, “Try clicking the button.” That’s insufficient. Instead, provide a numbered sequence: “1. Navigate to the homepage. 2. Click on the ‘Submit’ button located in the top-right corner. 3. Observe that the page does not refresh and no confirmation message is displayed.” This level of detail provides developers with the exact instructions needed to replicate the issue. Remember, your goal isn’t just to point out a problem; it’s to empower someone else to solve it.
Finally, consider the tone of your report. While frustration is understandable when encountering bugs, avoid accusatory language or blaming specific individuals. Focus on the problem itself. Instead of “John broke it,” write: “The application fails to save changes after submitting a form.” A professional and objective tone fosters collaboration and avoids defensiveness. Utilizing phrases like “As a result…” or “Consequently…” helps to clearly articulate the impact of the bug. Remember, the aim is to facilitate a productive discussion and swift resolution.