Bug report template for websites

The template

Copy it into your tracker, your ticket form or an email. Every field answers a question the developer would otherwise have to ask.

Title: [What is broken] on [which page]

Page: https://…
What happened:
What I expected:

Steps to reproduce:
1.
2.
3.

How often: every time / sometimes / once
Who is affected: everyone / some visitors / only me
Severity: blocks a sale or a sign-up / annoying / cosmetic

Browser and device: (e.g. Chrome 140 on Windows 11, window 1440×900)
Screenshot or recording:
Console errors:
Failed requests:

## What happened
<!-- One or two sentences, in the words of whoever found it. -->

## What I expected

## Steps to reproduce
1.
2.
3.

## Where
- Page: https://…
- Browser and device:
- How often:

## Evidence
- Screenshot:
- Console errors:
- Failed requests:

## Severity
- [ ] Blocks a sale, a sign-up or a login
- [ ] Annoying, with a way around it
- [ ] Cosmetic

For Word or Google Docs, paste the plain text version: one report per page, the field names in bold. A spreadsheet is better past a handful of bugs, because it can be sorted by severity and filtered by status.

What goes in each field

Title: what is broken, and where

Write “Pay invoice button does nothing on the invoice page” rather than “Bug” or “Payments broken”. A title like that lets somebody find the report again, and spot the duplicate before filing it twice. There are more bug title examples below.

What happened, and what you expected

Write one sentence for each. The second matters as much as the first, because half of all “bugs” are a feature working in a way the reporter did not expect, and saying what you expected settles which it is.

Steps to reproduce

Give the shortest path from a fresh page to the problem. If the developer can make it happen, they usually fix it the same day; if they cannot, it waits. How to write them, with examples: steps to reproduce a bug.

How often, who, and how bad

“Every time, for every client paying by card” and “once, for me” are different bugs to a team deciding what to fix this week.

Browser, device, console errors, failed requests

Developers solve most bugs from these fields, and reporters leave them empty, because finding them means opening the browser’s developer tools. The console error names the file and line that failed; the failed request says whether it was the page or the server.

A good bug report, as an example

Title: "Pay invoice" button does nothing on the invoice page

Page: https://app.example.com/invoices/4821
What happened: I pressed "Pay invoice". The button showed a spinner for a second and went back to normal. No payment, no message.
What I expected: the card form, then a confirmation.

Steps to reproduce:
1. Open any unpaid invoice.
2. Press "Pay invoice".

How often: every time
Who is affected: every client paying by card (checked with two accounts)
Severity: blocks a payment

Browser and device: Chrome 140 on macOS, window 1440×900
Console errors: TypeError: Cannot read properties of undefined (reading 'clientSecret') at checkout.js:88
Failed requests: POST /api/payments → 500 (Internal Server Error), 312 ms

The console error and the 500 show that the payment server failed and the page did not handle it, so the developer knows where to look before opening the page.

More bug report examples

A layout bug on a phone

Title: "Add to cart" button hidden behind the cookie banner on phones

Page: https://shop.example.com/products/linen-shirt
What happened: on a phone, the cookie banner covers the bottom of the screen, and "Add to cart" sits under it. Scrolling does not move it out.
What I expected: to see and press "Add to cart" with the banner open.

Steps to reproduce:
1. Open the page on a phone, in a private window (so the banner shows).
2. Scroll to the bottom of the product description.

How often: every time
Who is affected: every first-time visitor on a phone
Severity: blocks a sale

Browser and device: Safari 18 on iPhone 15, 393×852
Screenshot: attached, banner and hidden button outlined

A bug that only happens sometimes

Title: Saving a draft sometimes shows "Something went wrong"

Page: https://app.example.com/posts/new
What happened: I pressed "Save draft" and got "Something went wrong". Pressing it again worked.
What I expected: "Draft saved".

Steps to reproduce:
1. Write a post of a few paragraphs.
2. Leave the tab open for 30 minutes or more.
3. Press "Save draft".

How often: 3 times this week, always after a long pause
When: 27 September, 14:05 CET
Browser and device: Edge 140 on Windows 11
Failed requests: POST /api/drafts → 401 (Unauthorized)

The 401 says the session had expired and the page did not handle it, which explains why it only happens after a long pause. Without that line, this report reads as “cannot reproduce”.

Bug title examples

A good title says what is broken, where, and for whom when it is not everyone. Someone scanning a list of fifty should know which one is theirs without opening it.

A bad one, and the same one rewritten

Title: Site broken

The payment doesn't work, can you look asap?

Which page? Which payment? What does “doesn’t work” look like? On which browser? Every one of those is a message back and a day lost. The good example above is this same bug, rewritten with the answers already in it.

The fields nobody fills in

A client, a colleague or a customer will write what happened. They will not open developer tools to copy a console error or a failed request, and they should not have to. Broken Here puts a button on the site for this. The reporter clicks the broken element and writes one sentence, and the ticket that reaches your tracker already has the page, the browser, the console errors, the failed requests and a screenshot. Try it on the demo, or check a page for the errors it would catch.

• What happened: typed by the reporter.
• Page, browser, device, window size: captured.
• Console errors and failed requests, with the moment they happened: captured.
• Screenshot, with password fields blurred before it leaves the browser: captured.