Most bug report templates floating around the internet are PDFs from 2014 with fields like "Tester ID" and "Module Name." This is a working bug report template for 2026 — Markdown for engineering teams, plain text for non-technical clients, with a real severity rubric and examples. Plus an honest note: if your team uses GitHub or Linear, you can probably skip the template entirely and let a tool capture the same data automatically.
A bug report is a contract between the person who saw the bug and the person who has to fix it. Every field exists for one reason: the developer can reproduce the issue locally without going back to ask follow-up questions. If a developer has to ping the reporter for a clarification, the report failed. The eight fields below are the minimum that prevents that ping.
This 8-field structure is the foundation for every bug report format we'll cover below — Markdown, plain text, and the auto-generated version. The fields are the same; only the syntax and who fills them in changes.
Copy this and paste it into a GitHub Issue, Linear ticket, Jira description (with Markdown enabled), or a .github/ISSUE_TEMPLATE/bug.md file. It's the canonical software bug report template for any engineering team that lives in a Git-based tracker.
## Title
<One sentence: what broke + where. Example: "Checkout button returns 500 on /cart when cart contains a deleted product.">
## Environment
- URL: https://app.example.com/cart
- Browser: Chrome 145.0.7341.92 (arm64)
- OS: macOS 15.2 (Sequoia)
- Viewport: 1440 × 900
- App version: v2.18.4 (commit a3f9e21)
- User role: authenticated, plan=pro
- First seen: 2026-04-18 14:22 UTC
## Steps to reproduce
1. Log in as [email protected]
2. Add product SKU DEMO-42 to cart
3. In another tab, soft-delete SKU DEMO-42 from admin panel
4. Return to cart tab and click "Checkout"
## Expected
Cart should refresh and show "This product is no longer available — remove from cart?" with a Remove button. Checkout flow should not start.
## Actual
Page POSTs to /api/checkout/create, server returns 500 Internal Server Error. UI shows generic "Something went wrong" toast. Cart is left in a broken state — refreshing the page reproduces the same error.
## Screenshot / Recording
<attach screenshot or paste Loom URL>
## Severity
S2 — Major (blocks checkout for any cart containing a deleted product; affects revenue but workaround exists: clear cart and re-add)
## Console / Logs
// Browser console
POST https://app.example.com/api/checkout/create 500 (Internal Server Error)
Uncaught (in promise) TypeError: Cannot read properties of null (reading 'price')
at CartSummary.render (CartSummary.tsx:84)
at processChild (react-dom.js:3108)
// Server log (correlation id 7f3a-9e21)
[ERROR] CheckoutService: product DEMO-42 returned null from ProductRepository.findActive()
at CheckoutService.calculateTotal (checkout.service.ts:127)
## Additional context
- Reproduces 100% of the time with any soft-deleted SKU
- Did not exist before deploy a3f9e21 (yesterday)
- Likely related to PR #412 (refactored ProductRepository)
| Severity | Definition | Example | Response time |
|---|---|---|---|
| S1 — Critical | Production down, data loss, security breach, or no workaround for any user | Login broken for all users; payment double-charges; database leak | Drop everything < 1 hr |
| S2 — Major | Core feature broken for many users, or any user with no easy workaround | Checkout fails on certain carts; export to CSV produces empty file | Same day |
| S3 — Minor | Non-core feature broken, or core feature broken with easy workaround | Search returns wrong order; tooltip text wrong; date picker broken in Safari only | Within sprint |
| S4 — Trivial | Cosmetic; no functional impact | Button is 2px off-center; placeholder text has typo; hover color slightly off | When convenient |
For a client, support agent, or stakeholder who shouldn't have to learn what a "stack trace" is. Five fields, no jargon. Anyone can fill it out in two minutes.
WHAT PAGE OR SCREEN
(paste the URL or describe where you were — "the cart page", "the dashboard")
WHAT YOU DID
(in your own words, what you clicked, typed, or tried to do)
WHAT HAPPENED
(what you actually saw — error message, blank screen, wrong result, etc.)
WHAT YOU EXPECTED
(what you thought should happen instead)
SCREENSHOT
(attach a screenshot if you can — Cmd+Shift+4 on Mac, Win+Shift+S on Windows)
That's it. The QA lead, support engineer, or developer who picks up the ticket can fill in the technical fields (browser, console errors, severity) afterwards if they need to. The point of the plain-text version is to lower the friction for the reporter — a five-field form gets filled in; an eight-field form gets abandoned or filled in badly.
After reading thousands of bug reports across client projects, the same five anti-patterns appear over and over. Every one of them eats developer time and forces a follow-up "can you give me more detail?" message that the reporter sees three days later.
/admin/users/482/settings looks identical to /admin/users/483/settings, but the bug only exists on user 482.Here is the honest part. If your team uses GitHub, Linear, or any modern tracker, the bug report template above is solving a 2010s problem. The 2026 version is: a tool that captures all 8 fields automatically when the reporter clicks the broken element.
The side-by-side is stark. Templates are a workaround for the absence of tooling. When tooling exists, the workaround is no longer needed.
The template still has its place. If your reporter doesn't have Chrome, or you need a paper trail in a Word doc for compliance, or your client refuses to install extensions, the Markdown and plain-text templates above are the right tool. For everyone else: skip the template, install VibeCheck.
| Tool | How fields are filled | Pricing | Best for |
|---|---|---|---|
| GitHub Issues | Manual via ISSUE_TEMPLATE/bug.md | Free | Open source, dev-facing repos |
| Linear | Manual via templates | $8/user/mo | Product teams that already live in Linear |
| Jira | Manual + plugins (Marker.io, Bugasura, etc.) | $8.15/user/mo + plugin cost | Enterprise QA workflows |
| Marker.io | Semi-auto: click element, fills env + screenshot, manual description | $39/mo (Essential) | Agencies doing client UAT |
| VibeCheck | Fully auto: click element, all 8 fields filled, manual one-line description | Free | Devs and PMs who want fixes, not tickets |
Compare alternatives in detail: BugHerd alternatives, Usersnap alternatives, and Marker.io vs Vibers.
What should a bug report include?
A complete bug report includes 8 fields: a clear title (what broke + where), environment (URL, browser, OS, app version), exact steps to reproduce numbered 1-2-3, expected behavior, actual behavior, a screenshot or screen recording, severity (S1 critical to S4 trivial), and console errors or stack traces. Reports missing any of these usually bounce back to the reporter with "cannot reproduce" or sit in the backlog while a developer guesses what was meant.
What's the difference between a bug report and a defect report?
In practice, the terms are used interchangeably. Formally, a "defect" is a deviation from the specification (something the software was built to do but does incorrectly), while a "bug" is a broader category that includes defects plus issues like performance regressions, UX problems, and edge cases not covered by the spec. ISO/IEC 25010 uses "defect." Most engineering teams use "bug." The reporting template is identical for both.
How do I write a bug report for a non-technical team?
Use the simplified 5-field plain-text version above: what page or screen, what you did, what happened, what you expected, screenshot. Drop technical fields like console errors, stack traces, and browser version — the QA lead or developer can fill those in later if needed. The goal for non-technical reporters is capturing the user-visible problem clearly enough that someone technical can reproduce it. Even better, give them a tool like VibeCheck that auto-captures the technical fields from a single click.
Is there a free bug report template I can copy?
Yes — both versions in this article are free to copy. The Markdown bug report template is designed for GitHub Issues, Linear, Jira (with Markdown enabled), and any developer-facing tracker. The plain-text version is for clients, support agents, and stakeholders who don't write Markdown. No signup required, no PDF download, no email gate. Copy the code block and paste it into your issue tracker as a template.
Can I auto-generate bug reports?
Yes. Tools like VibeCheck (free Chrome extension), Marker.io ($39/mo), BugHerd, and Usersnap let a reporter click an element on the page and auto-capture the URL, screenshot, browser, OS, viewport, console errors, and DOM path. The reporter only types the description. This eliminates 6–7 of the 8 template fields and removes the most common failure mode of bug reporting: missing or incorrect environment data.
What format is best — Markdown, Word, or PDF?
For internal engineering teams: Markdown, every time. It pastes cleanly into GitHub, Linear, Jira, and Slack, renders well in any text editor, and is version-controllable. For external clients without technical tooling: plain text or a simple Word doc. Avoid PDF — it forces the reader to retype information into the issue tracker, which is where most data loss happens. The bug report format should match the workflow of the people who fix bugs, not the people who file them.
VibeCheck captures URL, browser, OS, screenshot, console errors, and DOM element from a single click. Reporter types one sentence. Free Chrome extension, no subscription, works on any URL.
Try VibeCheck Free Or get human review →