Flawsnap
Free trial

Bug report template you can copy and paste

A plain-text template that works in any tracker, a guide to each field, and a worked example.

A bug report template is a fixed set of fields every report fills in: title, summary, steps to reproduce, expected result, actual result, environment, evidence, frequency and priority. Using the same template for every report makes bugs faster to triage and reproduce, because developers always know where to find each detail. Copy the template below.

The template

Paste this into your tracker's issue template, a shared doc or an email. It is plain Markdown, so it renders well in most tools and stays readable where it does not.

Bug report template (Markdown)
## Title
[Where] [what goes wrong] when [trigger]

## Summary
One or two sentences: what is wrong and who it affects.

## Steps to reproduce
Starting point: [URL, signed in or out, account type]
1.
2.
3.

## Expected result
What should have happened.

## Actual result
What happened instead. Include any message shown on screen.

## Environment
- Browser and version:
- Operating system:
- Device and screen size:
- Account or role used:
- Build, release or environment (production, staging):

## Evidence
- Screenshot (problem marked):
- Recording:
- Console errors:
- Failed network requests (method, URL, status):

## Frequency
Every time / sometimes (about how often) / once

## Priority
Critical / High / Medium / Low, and why

What each field is for

FieldWhy it mattersCommon mistake
TitleLets someone triage the report without opening itNaming the feature but not the failure
Steps to reproduceThe developer's first action is to follow themSkipping the starting state, such as being signed in
Expected resultShows whether it is a bug or a misunderstandingLeaving it out because it seems obvious
Actual resultDescribes the symptom preciselyWriting "it doesn't work"
EnvironmentMany bugs depend on browser, width or roleWriting "latest Chrome" instead of the version
EvidenceErrors and failed calls often point straight at the causeA cropped screenshot with no URL visible
FrequencyIntermittent bugs need a different approachNot saying it only happened once
PriorityOrders the queueMarking everything Critical

A filled-in example

Here is the template completed for a real-looking layout bug on a booking site.

Example: filled-in bug report
## Title
Booking form: date picker hidden behind footer on small phones

## Summary
On narrow screens the calendar opens underneath the sticky footer,
so visitors cannot pick a date or complete a booking.

## Steps to reproduce
Starting point: https://example.com/book, signed out
1. Open the page on a phone about 360px wide.
2. Scroll to "Choose a date".
3. Tap the date field.

## Expected result
The calendar opens above the footer and every day can be tapped.

## Actual result
The calendar opens, but the bottom two rows are behind the footer
and cannot be tapped. Dates after the 21st cannot be chosen.

## Environment
- Browser and version: Chrome 130 (Android)
- Operating system: Android 14
- Device and screen size: Pixel 6a, 360 x 800 viewport
- Account or role used: none (signed out)
- Build, release or environment: production

## Evidence
- Screenshot (problem marked): attached, footer boxed in red
- Recording: none
- Console errors: none
- Failed network requests: none

## Frequency
Every time below roughly 400px wide. Fine on tablets and desktop.

## Priority
High: it blocks bookings for late-month dates on small phones.

A short version for non-technical reporters

Clients and customers will not fill in nine fields. For them, ask three questions and collect the rest automatically or in a follow-up:

  • What were you trying to do?
  • What happened instead? (A screenshot is ideal.)
  • Which page were you on?

A website feedback widget can answer the third question and the whole environment section for them. Flawsnap attaches the page URL, browser, device, console and network requests to every report automatically.

Adapting the template for a mobile app

Swap the browser fields for app version and build number, device model, OS version and light or dark mode. Add the screen name you were on, because apps have no URL. If the app was recently updated, say whether the bug appeared after the update.

Making the template stick

  • Put it where reports are created: most trackers let you set a default issue template.
  • Reject nothing for being incomplete, but reply with the missing field's name so the habit forms.
  • Review the template every few months and remove any field nobody fills in.
  • For guidance on writing each part well, read how to write a bug report.

Questions

Which fields are essential if I want a shorter template?
Title, steps to reproduce, expected result, actual result and a screenshot. With those five, most bugs can be reproduced. Environment details matter mostly for layout and browser-specific bugs, and are best captured automatically.
Can I use this template in Jira, GitHub or Linear?
Yes. It is plain Markdown, which those tools and most others render. Paste it into the tool's issue template settings so every new issue starts with it.
Should the template differ for feature requests?
Yes. A feature request has no steps to reproduce or actual result. Use a separate template that asks who needs it, what problem it solves and how they work around it today.

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