Flawsnap
Free trial

How to write a bug report developers can act on

Seven habits that turn "it is broken" into a report someone can fix without asking you anything.

A good bug report lets someone else reproduce the problem without asking you questions. Give it a specific title, numbered steps from a known starting point, the result you expected, the result you got, the browser or device you used, and evidence such as a marked-up screenshot or console error. Report one bug per report.

The seven habits

  1. 1

    Reproduce it once more before you write

    Try the same steps again. If it happens every time, say so. If it happens one time in five, say that instead: intermittent bugs need different investigation, and knowing which kind it is saves hours.

  2. 2

    Write a title that names the place, the action and the failure

    Use the pattern [where] [what goes wrong] when [trigger]. "Checkout: Pay button does nothing when a discount code is applied" can be triaged from the title alone. "Payment issue" cannot.

  3. 3

    List the steps from a known starting point

    Start somewhere anyone can reach: a URL, a logged-out state, an empty basket. Number each step and keep it to one action. Include the data you used, such as the product, the discount code or the account type.

  4. 4

    Separate expected from actual

    Write what you thought would happen and what did happen as two separate lines. Sometimes the "bug" is a misunderstanding of how a feature works, and this makes that obvious quickly.

  5. 5

    Record the environment

    Browser and version, operating system, device, screen size, and whether you were signed in. Layout bugs often appear at one width only, and some failures are specific to one browser.

  6. 6

    Attach evidence

    A screenshot with the problem circled, a short recording of the steps, and any red errors from the browser console. If a request failed, its URL and status code are often the fastest route to the cause.

  7. 7

    Keep it to one bug

    If you found three problems, file three reports. Bundled reports get half-fixed and then closed, and the remaining issues are lost.

Before and after: the same bug, reported twice

Before: "Discount codes don't work, please fix asap."

A developer reading this has to ask which code, which page, which browser, what "don't work" means, and whether it is all codes or one.

After:

  • Title: Checkout: Pay button does nothing after applying code WINTER10
  • Steps: 1. Open /shop and add "Wool scarf" to the basket. 2. Go to /checkout. 3. Enter WINTER10 and click Apply. 4. Click Pay.
  • Expected: The payment form opens with the 10% discount shown.
  • Actual: The discount appears in the total, but clicking Pay does nothing. No message is shown.
  • Environment: Chrome 130 on Windows 11, 1366 x 768, signed in as a returning customer.
  • Evidence: Screenshot with the Pay button circled. Console shows "TypeError: Cannot read properties of undefined (reading 'amount')". POST /api/checkout returned 422.
  • Frequency: Every time with WINTER10. Works without a code.

The "after" version takes about two minutes longer to write and usually saves a day of back-and-forth.

Severity and priority are different things

Severity is how bad the effect is: data loss and blocked payments are severe; a misaligned icon is not. Priority is how soon it should be fixed, which also depends on how many people hit it and what is coming up. A typo on the homepage the day before a launch can be low severity and high priority.

If your tracker has only one field, use it for priority and describe the impact in the description.

Mistakes that slow fixes down

  • Describing your theory of the cause instead of what you saw. Report the symptom; let the investigation find the cause.
  • Cropping the screenshot so tightly that nobody can tell which page it is.
  • Writing "same as before" or "see last week's email" instead of repeating the steps.
  • Pasting a photo of the screen taken with a phone, which hides the URL and blurs text.
  • Leaving out that you were using a test account, a VPN or a browser extension that changes pages.
  • Reopening an old, closed report for a new problem that only looks similar.

Letting the tool do the tedious part

Most of the environment section and all of the console and network evidence can be captured automatically. A tool like Flawsnap adds a report button to your site that attaches the page, browser, device, recent console messages and network requests to every report, so the reporter only writes the title, the steps and what they expected. If you want a structure to paste into any tracker, use the bug report template.

Questions

How long should a bug report be?
As short as possible while still letting someone reproduce the bug. For most bugs that is a title, three to six steps, an expected and an actual line, and a screenshot. Long narrative paragraphs are usually a sign the report covers more than one problem.
What if I cannot reproduce the bug?
Report it anyway and say so plainly. Include the time it happened, what you were doing, the page URL and any screenshot you managed to take. Several "could not reproduce" reports about the same area often reveal a pattern.
Should I suggest a fix in the report?
Only as a clearly separate note after the facts. A suggested fix is helpful when you know the system, but it should never replace the steps, the expected result and the actual result.
Who should set the priority?
The reporter can suggest one, but the person who triages the backlog should decide, because they can weigh it against everything else in progress.

Try it on your own site

7-day free trial, then $9 a month for Starter or $19 for Pro, per organization, with unlimited team members.

Start free trial Try the live demo

Related

Updated