How to Write a Good Bug Report (With Examples)

A bug report is only as useful as the information inside it. "The site is broken" tells a developer nothing. "The checkout button does nothing on iPhone Safari when my basket has more than one item" tells them where to look, what to test, and roughly how bad it is. The difference between those two reports is the difference between a bug fixed today and a bug that bounces back and forth for a week.

This guide walks through exactly what a good bug report contains, shows a bad report next to a good one, and gives you a checklist you can reuse every time.

Why bug reports go wrong

Most poor reports aren't written by careless people. They're written by people who already know what they saw and forget that the reader doesn't. You watched the error happen. The developer didn't. Every detail that lived only in your head — the page you were on, the browser you used, what you clicked — has to be written down, or it's lost.

The goal is simple: give someone who has never seen the problem everything they need to reproduce it themselves. If they can reproduce it, they can almost always fix it.

What a good bug report contains

A clear, specific title

The title should summarise the problem in one line. Aim for the shape "what breaks, where, under what condition."

Bad: "Broken"
Better: "Checkout button unresponsive on mobile with multiple items in basket"

Steps to reproduce

Number them. Start from a known state ("logged in as a standard user, on the homepage") and list every action until the bug appears. If you can't reproduce it reliably, say so and note how often it happens.

Expected vs actual result

State both explicitly. This is the single most valuable part of a report and the one most often skipped.

Expected: clicking "Pay now" takes me to the payment screen.
Actual: clicking "Pay now" does nothing; the page stays put.

Environment

Bugs often live in one specific setup. Include:

Device and operating system (e.g. iPhone 14, iOS 17)
Browser and version (e.g. Safari 17.2)
Screen size if it's a layout issue
Whether you were logged in, and as what kind of user

A screenshot or recording

A picture removes ambiguity instantly. Annotate it if you can — an arrow pointing at the broken element is worth a paragraph. For anything visual or intermittent, a short screen recording is even better.

Severity

Tell the team how much this hurts. Is it a cosmetic typo, or can nobody check out? A shared sense of severity is what stops trivial issues from jumping the queue ahead of a broken payment flow. On stopbuggin.me, reporters pick from four plain-language priority levels — from typo / visual through feature not working and can't complete task up to site broken — so non-technical reporters can flag urgency without guessing at engineering jargon.

Bad report vs good report

Here's the same issue reported two ways.

The bad version:

The payment page is broken, please fix ASAP!!!

There's nothing here to act on. Which page? Broken how? On what device? The developer has to reply and wait, and the clock keeps ticking.

The good version:

Title: "Pay now" button does nothing on iPhone Safari with 2+ basket items

Steps to reproduce:

On an iPhone, open the store in Safari.

Add two or more products to the basket.

Go to the basket and tap "Pay now".

Expected: the payment screen loads. Actual: nothing happens; the button appears to depress but the page doesn't change. No error message.

Environment: iPhone 14, iOS 17.2, Safari. Logged in as a standard customer. Works fine on desktop Chrome and with a single item in the basket.

Severity: Site broken — customers can't complete a purchase on mobile.

Screenshot: [attached, basket screen with two items]

The second report can be picked up and reproduced in minutes. Notice the detail that it works with a single item and on desktop — that narrows the cause dramatically before a developer has even opened the code.

The reusable checklist

Before you submit any bug report, run through this:

Title that names what breaks, where, and under what condition
Steps to reproduce, numbered, from a known starting state
Expected result — what should happen
Actual result — what actually happens
Environment — device, OS, browser and version, login state
Screenshot or recording, annotated where useful
Severity — how badly it affects users
Anything that narrows it down — what makes it appear or disappear

A few habits that help

Report one bug per report. Bundling three issues into one thread means two of them get forgotten.
Describe, don't diagnose. Say what you observed, not what you think the cause is. Guesses about the cause can send developers down the wrong path.
Include the "sometimes." Intermittent bugs are real bugs. Note the pattern you've spotted, even a vague one.
Don't assume it's obvious. The thing that's glaringly wrong on your screen may not reproduce at all on someone else's.

Good reports aren't about writing more — they're about writing the right things. The checklist above takes a couple of minutes and saves hours of back-and-forth. If you collect reports from clients or non-technical colleagues, a structured form that prompts for these fields (and captures a screenshot automatically) does most of this work for you — which is exactly what stopbuggin.me's public report forms are built to do.