How to Write a Bug Report Developers Actually Fix

Every developer has opened a bug report that says "checkout is broken" and nothing else. Every tester has had a bug bounced back with "cannot reproduce". Both people are annoyed, and the bug is still there.

Most of the time the gap isn't skill or attitude. The report just doesn't carry enough information to act on. A good one answers a developer's first questions before they have to ask them.

Here's a structure that works, plus a template you can paste into any tracker.

What a developer needs in the first 60 seconds

When a developer opens a bug, they're trying to answer four things:

1. Can I make it happen?
2. What did I expect to see, and what happened instead?
3. Where does it happen (browser, device, build, account type)?
4. How bad is it, and who is affected?

If the report answers those, work starts. If it doesn't, the first comment is a question, and the bug sits for a day.

The six parts of a useful report

1. A title that says what broke

Bad: Checkout error
Better: Checkout fails with a 500 error when the cart contains a discounted item and the coupon is removed

A good title names the feature, the failure and the condition that triggers it. Someone scanning a list of fifty bugs should be able to tell which one this is, and whether it duplicates another.

2. Steps to reproduce

Number them. Start from a known state, such as "logged in as a standard user with an empty cart", and keep each step to a single action.

1. Log in as a standard user (not admin).
2. Add "Notebook A5" (discounted) to the cart.
3. Apply coupon SAVE10.
4. Remove the coupon.
5. Click "Checkout".

Check the steps yourself, from scratch, before you submit. If you can't reproduce it a second time, say so and say how often it happened.

3. Expected result and actual result

Two short lines, kept apart:

Expected: the checkout page loads with the original price.
Actual: a blank page appears and the network call returns 500.

The expected line matters more than people think. Without it, a developer can't tell whether you've found a bug or a misunderstanding of the requirement.

4. Environment

Include only what could affect the result:

• Browser and version, or device and OS version
• App build or release number
• Environment (staging, production, local)
• Account type, role or feature flags involved

"Works on my machine" usually means the environments differ. Put the difference in the report and you've done half the debugging.

5. Evidence

Attach something a developer can look at without guessing:

• A screenshot or short screen recording
• The exact error message, copied as text
• Console errors or the failing network request (URL, status, response body)
• Relevant log lines and timestamps

Evidence you can search for, like a request ID or an error code, saves the most time.

6. Impact and frequency

One line each. Who is affected (everyone, one role, one device)? How often does it happen (always, one in five)? Is there a workaround? This is what lets the team decide whether it's a drop-everything bug or a next-sprint one.

Before and after

Before

Title: Search not working
Search is broken. Please fix ASAP.

After

Title: Search returns no results for queries containing an apostrophe (e.g. "O'Brien")

Steps:

1. Log in as any user.
2. Open Contacts and type O'Brien in the search box.

Expected: contacts named O'Brien are listed.
Actual: "No results found", although the contact exists.

Environment: Chrome 130, staging, build 2.14.1
Evidence: screenshot attached; the request to /api/contacts?q=O'Brien returns 200 with an empty list.
Impact: affects every user searching a name with an apostrophe. Workaround: search without the apostrophe.

The second one takes four minutes longer to write. It saves the developer, and you, a round of questions.

A copy-paste template

**Title:** <feature> fails <how> when <condition>

**Steps to reproduce**
1.
2.
3.

**Expected result**

**Actual result**

**Environment** (browser/device, build, environment, account/role)

**Evidence** (screenshot/recording, error text, request, logs)

**Impact and frequency** (who, how often, workaround?)

A short checklist before you hit submit

• Could someone who has never seen this feature reproduce it from my steps?
• Did I separate expected from actual?
• Did I include the exact error text, not a paraphrase?
• Did I search for a duplicate first?
• One bug per report?

If you're the developer reading it

Developers can help too. When you can't reproduce a bug, reply with what you tried and what's missing, not just "cannot reproduce". A specific question gets a specific answer. "I tried Chrome 130 on staging with a standard user and the search worked. Is the contact in a shared list?" moves things forward.

Keep bugs where the work happens

A report is only useful if it stays attached to the work. Whatever tracker you use, make sure each bug has an owner, a status and a link to the fix. In ProjTL, for example, a bug is a task type, so it sits alongside the rest of the work with its own owner and date. The tool matters less than having one place where nothing gets lost.

The takeaway

A good bug report isn't longer, it's more complete: a clear title, steps anyone can follow, expected against actual, the environment, evidence and impact. Write for the person who'll read it at the end of a long day, and more bugs will get fixed the first time.

What do you wish more bug reports included? Share it in the comments.