How to write a bug report developers can fix
A bug report has one job: let someone who was not there see what you saw. Every question a developer has to ask before they can start is a round trip, and round trips are where bugs go to wait. A report that answers those questions up front is usually fixed on the first read.
This guide covers what to put in a report, why each part earns its place, and the mistakes that make good reports useless. There is a copyable template at the end, and a free bug report generator that fills in your browser details for you.
The test of a good bug report
Hand the report to a developer who has never seen the page. Can they make the bug happen on their own machine without talking to you? If yes, the report is good. If they need to message you first, something is missing, and it is almost always one of three things: where it happened, what you did, or what you were running.
Notice what the test does not ask for. It does not ask for a diagnosis. You do not need to know why the button is broken, which service failed, or whose fault it is. Guesses are fine if you label them as guesses, but the facts are what get bugs fixed.
The seven parts of a bug report
1. A summary that names the thing and the failure
The title is what people scan in a list of fifty issues, so it should say what broke and where. “Checkout broken” is a category. “Pay now button does nothing on the payment step” is a bug. A good pattern is thing + what it does wrong + where. Leave out words like “urgent” or “again”: priority is a separate field, and frustration does not help anyone find the line of code.
2. Steps to reproduce
Numbered, one action per step, starting from a place anyone can reach: a URL, a fresh login, an empty cart. Write what you did, not what you meant to do. “Clicked Save” is better than “saved the form”, because there may be two ways to save and only one of them is broken.
If the bug only happens sometimes, say so and say how often: “about one in five tries”. Intermittent bugs are real bugs, and the frequency is a clue.
3. Expected result
One sentence on what should have happened. This sounds obvious, but it is the part that separates a bug from a misunderstanding. Sometimes the developer reads “expected” and realises the product works as designed and the design is what needs to change. That is a useful outcome too, and it only happens if you write the expectation down.
4. Actual result
What happened instead, as precisely as you can. Quote error messages word for word; a paraphrase cannot be searched for in the codebase and an exact string can. If nothing happened, say “nothing happened” and describe what “nothing” looked like: did the button stay enabled, did a spinner run forever, did the page reload?
5. Where: the URL and the element
Paste the full URL, including anything after the ?. Query strings often carry the state that triggers a bug. If the problem is with one element on a busy page, describe it so it cannot be confused with its neighbours: “the second Pay now button, in the order summary on the right”, not “the button”.
6. Environment
Browser and version, operating system, and screen size. Many bugs only exist in one browser or below a certain width, and without this a developer will test in their own setup, see nothing wrong, and close the report as “cannot reproduce”. Mention the account or role you used if the app behaves differently for different users, but never paste a password.
7. Evidence
A screenshot with the problem circled, a screen recording of the steps, and, if you can open the browser’s developer tools, any red errors in the console. Evidence settles arguments about what happened. A recording is especially valuable for bugs that depend on timing or a long sequence of steps.
Mistakes that sink good reports
- Several bugs in one report. They get fixed at different times by different people, and a report cannot be half closed. One bug, one report.
- “Doesn’t work.” Without expected and actual, nobody can tell what “work” means to you.
- Screenshots without context. A cropped image of an error, with no URL and no steps, shows that a bug exists but not how to reach it.
- Reporting from memory. Write the report while the page is still open. Details you are sure you will remember are the first to go.
- Sensitive data. Do not paste passwords, card numbers or a customer’s personal details into a ticket. Describe them instead (“a Visa test card”).
A bug report template you can copy
Paste this into GitHub, Linear, Jira or a Slack message and replace the example text. It is written in Markdown, so headings and lists render in most trackers.
## Summary
Checkout button does nothing on the payment step
## Steps to reproduce
1. Add any item to the cart
2. Go to /checkout and fill in the shipping form
3. Press "Continue to payment"
4. Press "Pay now"
## Expected
The order is placed and the confirmation page opens.
## Actual
Nothing happens. The button stays enabled; no error is shown.
## Environment
- URL: https://example.com/checkout/payment
- Browser: Chrome 130 on macOS 15
- Screen: 1440 × 900
- Account: [email protected] (any account reproduces it)
## Notes
Started after Tuesday's deploy. Works in Firefox.Prefer a form? The bug report template generator asks for the same fields, detects your browser and operating system, and gives you the Markdown with a Copy button. Nothing you type leaves your browser.
When the reporter is not a tester
Everything above assumes the person reporting is willing to fill in seven sections. QA engineers are. Clients, founders and customers mostly are not, and asking them to learn a template is how feedback ends up as a vague email two weeks later. If your reporters are not professional testers, the better fix is to collect the context for them.
That is what Jot does. The reviewer clicks the broken element on the live page and types one sentence. The report arrives with the screenshot, the URL, the element’s CSS selector, the browser, operating system and screen size already filled in, and optionally a session replay with the console and network requests. The reporter writes the summary; the tool writes the environment and evidence. You can see how it is installed in the quickstart.
Checklist before you press Submit
- Does the title name the thing and the failure?
- Could a stranger follow the steps from a fresh start?
- Are expected and actual both written down?
- Is the full URL there?
- Browser, operating system and screen size?
- A screenshot or recording?
- Only one bug in this report?
If you can tick every line, the developer reading it can start fixing instead of starting a conversation. For a broader pre-launch pass, the website QA checklist covers what to test before you ship.