How to Write a Clear Bug Report in English
Learn how to write effective bug reports in English: steps to reproduce, expected vs actual behaviour, environment, severity, and before/after examples.
A clear bug report is one of the most valuable things you can produce as a developer, QA engineer, or technical user. A well-written bug report saves debugging time, reduces back-and-forth, and increases the chance that the issue is fixed quickly. A poorly written one wastes everyone’s time and may result in the issue being closed as “cannot reproduce.” This guide explains how to write effective bug reports in technical English.
The Core Components of a Bug Report
Every good bug report contains the same essential elements. Think of them as a recipe — skip an ingredient and the result suffers.
1. Title
A clear, specific title that describes the problem — not the symptom. It should answer “what breaks” and “where.”
Poor title:
“Login doesn’t work”
Better title:
“Login fails with 500 error when email contains a plus sign (+)”
A good title allows a developer to understand the scope of the issue before opening the report.
2. Environment
Specify the context in which the bug occurs. Without this, a bug may be impossible to reproduce.
“Environment: - Browser: Chrome 124.0 on macOS 14.3 - API version: v2.4.1 - Account type: Free tier - Region: EU (eu-west-1)”
For backend bugs, include server version, OS, relevant configuration flags, and database version.
3. Steps to Reproduce
A numbered list of exact steps to trigger the bug. Be precise — use exact values, not approximations.
Poor:
“Go to the dashboard and try to export.”
Better:
“Steps to reproduce: 1. Log in with a free-tier account. 2. Navigate to Dashboard > Reports. 3. Click ‘Export as CSV’. 4. In the date range picker, select a range longer than 90 days. 5. Click ‘Download’.”
The person fixing the bug should be able to follow these steps and see the same problem without asking you any questions.
4. Expected Behaviour
Describe what should happen — not what you want to happen, but what the documented or intended behaviour is.
“Expected behaviour: A CSV file containing the report data for the selected date range should begin downloading.”
5. Actual Behaviour
Describe what actually happens. Include exact error messages, error codes, and relevant log output.
“Actual behaviour: The download button becomes unresponsive. No file downloads. The browser console shows:
Error: Request failed with status code 504 (Gateway Timeout)”
6. Severity and Priority
Severity describes the impact of the bug on the system:
- Critical — system is unusable, data is lost, or security is compromised
- High — major feature is broken for all or most users
- Medium — feature is broken but a workaround exists
- Low — minor cosmetic issue or edge case with minimal impact
Priority describes how urgently it should be fixed — which is a business decision, separate from severity.
“Severity: High (core export functionality is broken for all users with date ranges over 90 days)“
Before and After: Full Example
Before (Poor Bug Report)
“Export is broken. I tried to export a report and it didn’t work. Please fix.”
This report provides no steps, no environment, no expected behaviour, and no error details. It will generate multiple clarifying questions before anyone can start investigating.
After (Good Bug Report)
Title: Export to CSV fails with 504 timeout for date ranges over 90 days
Environment:
- App version: 3.7.2
- Browser: Firefox 125 on Windows 11
- Account type: Business plan
Steps to reproduce:
- Log in as a Business-plan user.
- Go to Reports > Custom Report.
- Set date range to 1 January 2025 – 31 May 2025 (151 days).
- Click “Export as CSV.”
Expected behaviour: A CSV file downloads within 30 seconds.
Actual behaviour: The page shows a loading spinner for approximately 60 seconds, then displays “An error occurred. Please try again.” The network tab shows a 504 response from
/api/reports/export.Severity: High — the export feature is the primary way Business-plan users extract data for reporting.
Additional notes: The issue does not occur with date ranges of 89 days or fewer. Tested on Chrome 124 with the same result.
Useful Phrases for Bug Reports
- “The issue occurs consistently when…”
- “I was unable to reproduce the issue on the staging environment.”
- “The error message displayed is: [exact text]”
- “This behaviour does not match the documentation, which states…”
- “A workaround is to…, but this is not acceptable as a permanent solution.”
- “I have attached a screen recording demonstrating the issue.”
- “The issue first appeared after the deployment of version 3.7.0.”
A well-written bug report is a professional communication. It respects the time of the engineers who will investigate the issue, demonstrates that you have done your due diligence, and dramatically increases the speed of resolution. Take the extra ten minutes to write a thorough report — it will save far more time than it costs.