Jira bug report template
Steps to reproduce, what should have happened, what happened instead, and where. The questions a developer asks first, answered before anyone has to ask.
The template
[Area]: [what goes wrong] when [action]
- Priority
- Medium
- Labels
- needs-triage
Description
Steps to reproduce
- Go to [page or screen]
- [Do this]
- [Then this]
Expected result
[What should have happened]
Actual result
[What happened instead. Copy any error message exactly.]
Environment
- Version or build:
- Browser or device:
- Operating system:
- Test account or site (never a password):
How often
[Every time, sometimes or once. If sometimes, roughly how often.]
Screenshots and logs
[Attach a screenshot, recording or log. Remove personal data first.]
Done when
- Reproduced
- Cause noted in a comment
- Fix verified where it was reported
- Test added that would have caught it
Show it as Markdown
### Steps to reproduce
1. Go to [page or screen]
2. [Do this]
3. [Then this]
### Expected result
[What should have happened]
### Actual result
[What happened instead. Copy any error message exactly.]
### Environment
- Version or build:
- Browser or device:
- Operating system:
- Test account or site (never a password):
### How often
[Every time, sometimes or once. If sometimes, roughly how often.]
### Screenshots and logs
[Attach a screenshot, recording or log. Remove personal data first.]
### Done when
- [ ] Reproduced
- [ ] Cause noted in a comment
- [ ] Fix verified where it was reported
- [ ] Test added that would have caught it
What a good Jira bug report template contains
Steps to reproduce, starting from somewhere anyone can reach. What should have happened, and what happened instead, with any error message copied exactly. The environment: version, browser or device, operating system. Then how often it happens, and evidence such as a screenshot, a recording or a log, with personal data removed. A short checklist says when the bug is done.
The summary names the area, what goes wrong and when: “Checkout: total shows 0 after a coupon is removed”, not “Checkout broken”. Someone scanning a list of bugs should know which one this is without opening it.
When to use it
Use it for anything that worked, or should have worked, and does not. A report that answers these questions can be picked up without a round of questions back to the person who reported it.
The same sections work as a problem report or issue reporting template outside software: a wrong figure in a monthly report, a booking system that rejects a valid date, a process step that failed. Rename Environment to Where it happened if that reads better.
If a whole service is down, use the incident template instead: an outage needs an impact, a timeline and a status more than steps to reproduce.
Severity and priority
Severity is how badly the bug affects the people who run into it: data lost, a feature that cannot be used, or a cosmetic slip. Priority is how soon the team will fix it, which also weighs how many people it affects, whether there is a workaround and what else is waiting. A severe bug in a feature few people use can wait behind a minor one on the checkout page.
Jira has a Priority field. This template sets it to Medium and adds the needs-triage label, so whoever triages the bug can see it has not been judged yet. Severity goes in the Impact section of the Detailed version. If your project has a field of its own for severity, use that instead.
What each section is for
- Steps to reproduce
- Numbered, starting from somewhere anyone can reach. If the steps do not always reproduce it, say so.
- Expected result
- Separates a bug from a misunderstanding. Sometimes the expected result is the real question.
- Actual result
- The exact error text can be searched for. A paraphrase cannot.
- Environment
- Where most "works for me" answers end.
- How often
- A bug that happens now and then needs a different investigation from one that happens every time.
- Screenshots and logs
- A short recording often says more than the steps. Logs and screenshots can hold personal data, so check them first.
- Impact Detailed
- Lets whoever triages set a priority without asking.
- First seen Detailed
- A start date points to the change that caused it.
Sections marked Detailed are not in the template above. Switch them on in the generator, where you can also edit the text and the checklist.
Jira bug report examples
Four bug reports from different kinds of software, each written with this template. Each one can be reproduced by someone who has never spoken to the reporter. Impact and First seen are from the Detailed version.
Web app: a wrong total at checkout
- Summary
- Checkout: total shows 0 after a coupon is removed
- Steps to reproduce
- Add any item to the basket
- Go to checkout and apply a valid coupon
- Remove the coupon
- Expected result
- The total goes back to the full price.
- Actual result
- The total shows 0.00 and the Pay button stays enabled. Paying fails with “Payment could not be completed”.
- Environment
- Version or build: release 4.12, production
- Browser or device: current Chrome and Firefox
- Operating system: Windows 11 and macOS
- Test account or site: the shared shop test account
- How often
- Every time.
- Screenshots and logs
- Screen recording attached. No errors in the browser console.
- Impact Detailed
- Any customer who removes a coupon cannot pay. Workaround: reload the checkout page.
Mobile app: an upload that fails on mobile data
- Summary
- Android app: photo upload fails on mobile data
- Steps to reproduce
- Turn off Wi-Fi so the phone uses mobile data
- Open any job and tap Add photo
- Take a photo with the camera and tap Upload
- Expected result
- The photo uploads, more slowly than on Wi-Fi, and appears in the job.
- Actual result
- The progress bar stops about halfway, then “Upload failed. Try again.” appears. On Wi-Fi the same photo uploads.
- Environment
- Version or build: app 3.8.1
- Browser or device: two Android phones from different makers
- Operating system: Android 14 and 15
- Test account or site: the field-team test account; iPhone not tried yet
- How often
- Every time with photos from the camera. Small images from the gallery upload.
- Screenshots and logs
- Screen recording and the app log from Settings → Send logs attached.
API: a server error on valid input
- Summary
- Orders API: 500 error when the delivery note contains an emoji
- Steps to reproduce
- Send
POST /v2/orderswith a valid order - Put any emoji in
deliveryNote
- Send
- Expected result
201 Created, with the note stored as sent.- Actual result
500 Internal Server Errorwith the body{"error":"internal"}. No order is created.- Environment
- Version or build: API v2, staging and production
- Browser or device: not relevant; sent with curl and from the partner’s system
- Test account or site: the staging partner account
- How often
- Every time an emoji is in the note. Other non-English text, such as “Bjørnstadveien”, works.
- Screenshots and logs
- The request and response attached, with the API key removed, and the request ID from the response header so the server log can be found.
Internal tool: approved leave missing from a calendar
- Summary
- Leave planner: approved days do not appear in the team calendar
- Steps to reproduce
- As an employee, request two days of leave
- As that employee’s manager, approve the request
- Open the team calendar for that week
- Expected result
- The approved days show in the team calendar.
- Actual result
- They are missing from the team calendar. The employee’s own calendar shows them.
- Environment
- Version or build: the release deployed on 14 October
- Browser or device: Edge on company laptops
- Test account or site: two test users in the training department
- How often
- Every request approved since 14 October. Requests approved before that still show.
- Screenshots and logs
- Screenshots of both calendars, with names blurred.
- Impact Detailed
- Managers plan cover from the team calendar, so they may leave a shift uncovered. Workaround: check each person’s own calendar.
- First seen Detailed
- The day after the 14 October release.
None of these names a real customer or includes a password or key. Test accounts, roles and blurred screenshots are enough to reproduce a bug, and a bug report is read by more people than the reporter expects.
How to make this the starting point in Jira Cloud
Jira Cloud has no issue templates as such. These are the native ways to get this text into new bugs, as Atlassian’s own pages describe them, and where each one stops. Our guide to Jira issue templates in Jira Cloud compares them in more detail.
Team-managed projects: a default description for Bug
Each work type in a team-managed project can have a default description. Atlassian’s recap on JRACLOUD-4812 gives the path: Project settings → Issue types, select Description, and write the default text. Choose Bug and paste the template. It is one text per work type, for the description only, and it cannot contain a table (KB). The Medium priority and the needs-triage label have to be set by hand.
Company-managed projects: Atlassian’s workaround
Here the system Description field cannot have a default. Atlassian’s workaround gives a custom Paragraph field the template as its default value, puts that field on the Create screen in place of Description, and copies it into Description with a post function on the workflow’s Create transition. It works, but it changes a custom field, screens and a workflow, and Bug still gets one template.
Cloning a reference bug
Keep one bug that is never closed, with this template in its description, and copy it with ••• → Clone when you need another, as Atlassian’s Clone page describes. The copy’s summary starts with “Clone”, and the reference bug turns up in searches, on boards and in bug counts like any other. Anyone who can edit it can change the template for everyone.
Automation after the bug is created
An Automation rule can write the template into Description: the Work item created trigger, a condition on the work type, and an Edit work item action, as in Atlassian’s KB. It runs once the bug exists, so the person reporting it in the Create dialog still starts from an empty description. Every trigger, condition and action that runs counts toward your Automation usage, and a rule on Work item created runs for every new work item, even when its condition says no (usage doc).
None of these lets someone pick between bug templates in the Create dialog: a short one for bugs passed on from support, say, and a longer one with impact and first seen for testers. That is what an app adds.
Want this as a template people pick in Jira?
Issue Templates & Create Defaults for Jira gives each project a Templates page. Pick a template there and Jira’s own Create dialog opens with the summary, description with its checklist, labels and priority filled in. From version 2.9.0 a template can also set the assignee to the person using it, a due date a number of days ahead, and components, such as the part of the product a bug template is for. The person can change anything before creating, under Jira’s usual rules for required fields and permissions. Set a default template for Bug, and the Create dialog only names it: a line under Summary points to the Templates page. The app writes nothing into a form by itself. It can also set custom fields, such as a severity dropdown, and it runs on Jira Cloud only.
To take a template from this page into the app with its formatting, paste it into an issue’s description, then, as a project or Jira administrator, choose Save as template from the issue’s ••• menu.
Questions
What should a bug report include?
Steps to reproduce, the expected result, the actual result with any error message copied exactly, and the environment it happened in. Then how often it happens, and a screenshot, recording or log with personal data removed.
What is the difference between severity and priority?
Severity is how badly the bug affects the people who run into it. Priority is how soon the team will fix it, which also weighs how many people it affects, whether there is a workaround and what else is waiting. Jira has a Priority field. In this template, severity goes in the Impact section of the Detailed version.
Can I set a default bug report template in Jira Cloud?
In a team-managed project, yes: set it as the Bug work type’s default description in the project settings. In a company-managed project, the system Description field has no default. Atlassian’s workaround uses a custom Paragraph field and a workflow post function.
Can I use this bug report template in Word?
Yes. Copy for Jira puts the template on the clipboard as formatted text as well as plain text, so it can be pasted into a Word document with its headings and lists. Copy as Markdown suits tools that read Markdown, such as GitHub.
Related pages
Or build your own in the Jira issue template generator, and see what Jira Cloud does on its own.
- Jira issue templates in Jira Cloud Default description · Automation · Cloning · Where each one stops
- Jira templates with sub-tasks The same children under every epic or work item, with and without an app
- Jira default description A description template for each work type, in both kinds of project and with Automation
- User story template User story · Acceptance criteria · Context · Out of scope
- Task template What needs doing · Why · Notes
- Incident template Impact · Started · Current status · Timeline · Workaround
- Spike template Question · Timebox · Why it matters · Output
- Epic template Goal · Problem · Scope · How we will know it worked