Asked what should a bug report contain, the useful answer is a list of seven fields. A working bug report format has a title, the environment, the build, steps to reproduce, the expected result, the actual result, and evidence. That is the whole thing. Copy it, put it in your tracker as a template, and you will have removed most of the reason bugs sit in a queue nobody can act on.
The rest of this page is what goes in each field, a filled example, and the more uncomfortable point — that a template is a workaround for context the report should have carried by itself.
The template
Title
What breaks, where. "Checkout fails on card entry with a saved address", not "checkout broken".
Environment
Device, operating system, browser or app version. The specifics, not "on mobile".
Build
The exact version or commit. Without it, nobody can tell whether it is already fixed.
Steps to reproduce
Numbered, from a known starting state, including the data used.
Expected result
What should have happened. This is the field that decides whether it is a bug at all.
Actual result
What happened instead, including any error text, quoted exactly.
Evidence
Screenshot, recording, console output. The field people fill in most willingly.
Severity and priority are worth adding as separate fields if your tracker does not already have them. Severity is how badly it breaks; priority is how soon you will fix it. Jira keeps them apart for this reason, shipping default priority levels of Highest, High, Medium, Low and Lowest.
Resist adding an eighth field. Every field you add is a field somebody skips, and a half-filled long template is worse than a complete short one — it teaches people the form is optional.
A filled bug reports example
Templates are easy to agree with and hard to apply, so here is the same bug written badly and then properly.
As it usually arrives:
Checkout is broken on mobile, can’t pay
As it should arrive:
Title: Checkout fails at card entry when a saved address is selected
Environment: iPhone 14, iOS 18.2, Safari
Build: 4.12.0 (2261)
Steps to reproduce:
- Sign in as a returning customer with at least one saved address
- Add any item to the basket and go to checkout
- Select a saved address rather than entering a new one
- Enter card details and tap Pay
Expected: Payment is taken and the confirmation screen appears
Actual: Spinner runs for about 10 seconds, then “Something went wrong. Please try again.” No charge appears on the card
Evidence: Screenshot of the error, console output attached
The second version takes maybe ninety seconds longer to write and removes a day of back-and-forth. Note what is doing the work: step 3. The bug only happens with a saved address, and nothing in the first version would have led anyone to try that.
The bug report checklist
Before submitting, check five things:
- Could someone else follow your steps without asking you anything? If a step says "set things up as normal", it is not a step.
- Did you say what you expected? Skipping this is how "working as designed" arguments start three days later.
- Is the error text quoted exactly? Paraphrased error messages cannot be searched for in the codebase.
- Is the build in there? The most commonly skipped field, and the one that decides whether the bug is already fixed on main.
- Is it one bug? Two problems in one report get half-fixed and closed. Split them.
What most software bug reporting template advice misses
Almost every version of this article ends at the template. The reason teams keep rewriting theirs is that the template is not where the failure happens.
People write reports at the worst possible moment. Someone hits a bug while doing something else, with a task half-finished. Asking them to switch context, open a tracker, and reconstruct seven fields from memory is asking them to abandon what they were doing. Most people either write something terse or do not file at all — and the bugs that go unfiled are invisible in your metrics, which is why this problem never shows up as a problem.
The fields most often skipped are the ones a machine could fill. Environment, build, browser version, console output, the sequence of screens. A person is the worst available source for all of them and the only source for the two that matter: what they expected, and what they were trying to do.
Longer templates make reports worse. Every required field increases the cost of filing and lowers the completion rate. Teams respond to bad reports by adding fields, which reduces the number of reports without improving their quality.
If your template has more than about eight fields, it is not a template any more — it is a form, and forms get abandoned. Cut it back and move the mechanical fields into whatever is capturing them automatically.
What the tools capture, so your template does not have to
The feedback tools in this category exist mostly to fill the mechanical fields for you, and it is worth knowing what each actually collects before designing a template around it.
Marker.io captures a screenshot plus environment details — browser, operating system, webpage and screen size — on every plan, though a July 2026 comparison notes that console logs are reserved for higher tiers, and a separate comparison reports its Starter plan at $39 per month billed annually including Jira synchronisation, session replay, and developer tools such as console and network logs. Its licensing is unusual and useful here: Reporters, meaning customers or end users who submit through the widget, are free and unlimited, though a Reporter can only see the feedback they personally submitted.
Usersnap collects contextual metadata on submission including date and time, reporter email where requested, location, browser, browser version, operating system and browser size, and developers can attach custom application data alongside it. Its free plan is gated at 20 feedback items according to a ProductLed teardown, and Capterra lists its Startup plan starting at $99 per month.
Both illustrate the same point: the moment capture is automatic, five of the seven fields stop being a writing task. What remains is the expected result and the steps — and the steps can be captured too.
Why the template is a workaround
Here is the thesis, stated plainly because the rest of this page has earned it: a bug report template exists because reports arrive without context, and the template is an attempt to get a human to supply that context by hand. It works, imperfectly, at the cost of the reporter’s time and attention.
TraceItX takes the other route. The reporter is inside the app being tested, so a person presses a bubble or a keyboard shortcut, draws on the screenshot, blurs anything sensitive, and sends. What arrives is one AI-ready envelope carrying the annotated screenshot, console and network state, the device and app context, the build, and the trail of screens and actions that led to the bug. Five of the seven template fields are filled before anyone types a word, and the steps to reproduce are captured whether or not the reporter thought to write them down.
You still want a title and an expected result. Those are the two fields only a person can supply, and they are the two worth asking for.
Two things TraceItX does not do. It ships no ticketing integration of its own: reports arrive as signed webhooks, and someone on your team writes the receiver that maps envelope fields onto your tracker's fields. That is engineering work you should price in, and vendors whose product is built around that integration will not ask you for it. And on the web, TraceItX supports React only; there is no framework-agnostic build, so a Vue or server-rendered site cannot use it.
Worth knowing before you design around either approach: Jira Cloud enforces a hard limit of 700 fields per space from March 2026, calculated from the field configuration schemes associated with that space, and administrators are blocked from associating further fields once a space exceeds it. Custom fields per bug template are cheap individually and expensive in aggregate.
Start with the two-field version
If your reports are bad today and you want one change that works this week, do not roll out a seven-field template. Ask for two things: what you expected, and what happened instead. Add the rest once people are filing consistently.
And if the mechanical fields are what keep going missing, that is a capture problem rather than a discipline problem — the free tier has unlimited seats and takes about ten minutes to wire into a build, which is enough to find out whether your template was ever the bottleneck.