How to Write a Bug Report: Template, Examples & Tips
A bug report is a structured description of a software defect — what went wrong, where it happened, and how to reproduce it. The difference between a fix shipped in hours and a ticket that bounces between teams for weeks almost always comes down to how the report was written.
This guide covers everything you need to know about how to write a bug report that developers can act on immediately: the anatomy of an effective report, the most common mistakes, a ready-to-use template, real-world examples, and a quick checklist. Whether you're a QA engineer, project manager, developer, or freelancer — you'll walk away with a repeatable process.
What’s in this article
- Why do good bug reports matter?
- What should a bug report include? (8 components)
- How to write a good bug report (7 best practices)
- Bug report template (copy & use)
- Sample bug report examples: good vs. bad
- Most common bug reporting mistakes
- How a bug reporting tool can speed things up
- Quick checklist before you hit “Submit”
- FAQ
Why do good bug reports matter?
Every role in a software team experiences bug reports differently. For developers, a clear report means less time reproducing and more time fixing. For project managers, it means fewer follow-up rounds and more predictable sprint timelines. For testers, it's proof of thorough work. And for freelancers managing client sites, a well-structured report builds trust — no more endless email chains with vague screenshots.
Poor reports lead to a familiar loop: the developer asks for more info, the reporter sends another vague reply, and what could've been a 30-minute fix turns into a multi-day thread. Good bug reporting breaks that cycle.
What should a bug report include?
Every effective bug report format covers the same core components. Here's what each one means and why it matters:
| Component | What to write & why it matters |
| Title | A short, specific summary that answers three questions: What happened? Where? Under what conditions? Good: "Checkout button unresponsive on Safari 17 after adding promo code." Bad: "Button broken." |
| Environment | OS, browser + version, device type, screen resolution, app/build version. Many bugs only appear in specific environments — without this, the developer may never reproduce it. |
| Steps to reproduce | Numbered actions anyone can follow to trigger the bug. Be exact — "Click 'Add to Cart' on product #4521" beats "Add something to cart." If the bug is intermittent, note how often it happens (e.g., "3 out of 5 attempts"). |
| Expected result | What should have happened based on the spec, the design, or common sense. This helps developers confirm both the bug and the correctness of their fix. |
| Actual result | What actually happened. Copy error messages word-for-word. If the page just "does nothing," describe that too — a blank response is still a result. |
| Severity / priority | Severity = how badly the bug impacts users. Priority = how urgently it should be fixed. They're not always the same — a typo on the homepage is low severity but may be high priority. |
| Screenshots / video | An annotated screenshot with an arrow pointing to the broken element, or a short screen recording showing the exact flow. Visual evidence eliminates most follow-up questions. |
| Console logs | Browser console errors, network request failures, or relevant server logs. This is gold for developers — it often points them directly to the root cause. |
A visual feedback tool like Ybug captures most of this automatically. Every report submitted through the Ybug widget includes the browser, OS, screen size, page URL, and JavaScript console logs — without the reporter lifting a finger. As the bug reporting page puts it: "Better bug reports, fewer follow-ups."
How to write a good bug report
Knowing the components is one thing. Writing a report developers actually want to read is another. Here are 7 practices that separate actionable reports from noise — whether you're writing a software bug report for your team or submitting user feedback as a client.
1. One bug, one report
Don't bundle three issues into a single ticket. Each defect gets its own report. This keeps tracking clean, makes bug triage easier, and prevents fixes from getting tangled. If you're unsure whether two symptoms are the same bug, file separate reports — they can always be linked or marked as duplicates later.
2. Write a title that tells the whole story
A developer scanning a backlog of 50 tickets should understand your issue from the title alone. The best approach: include what happened, where, and when it's triggered.
| Title example | |
| ❌ Bad | "Login doesn't work" |
| ✅ Good | "SSO login fails with 'Invalid credentials' error on Chrome 120 (macOS)" |
| ❌ Bad | "Cart page error" |
| ✅ Good | "'Checkout' button on Cart page navigates to Error 500 after applying promo code" |
Notice how the good titles describe what is happening — not what isn't happening. "Login doesn't work" forces the developer to read the entire report. A specific title saves everyone time.
3. Make reproduction steps foolproof
This is the single most important section of any bug report. If a developer can't reproduce the issue, they can't fix it. Pretend the person reading your report has never seen the product. Number each step. Include exact URLs, input data, and user roles.
Compare these two descriptions of the same software bug:
Vague: "When you try to buy something, it crashes."
Clear:
1. Log in as a registered user at app.example.com/login
2. Navigate to Products > "Blue Widget" (SKU #4521)
3. Click "Add to Cart"
4. Go to Cart and click "Proceed to Checkout"
5. Enter promo code SAVE20 and click "Apply"
Expected: Discount is applied and order summary updates.
Actual: Page shows a blank white screen. Console logs: "TypeError: Cannot read property 'discount' of undefined."
The clear version gives the developer a direct path to the problem — including the exact data, the page, and the console error. That's the difference between a fix in 30 minutes and a "cannot reproduce" that sits in the backlog for weeks.
4. Separate facts from guesses
Describe what you observed, not what you think caused it. "The page returns a 500 error" is actionable. "I think the database is down" is speculation — unless you have server logs to back it up. If you have a theory, add it in an "Additional notes" section clearly marked as a guess.
5. Attach visual proof
A screenshot with an arrow pointing to the broken element saves a thousand words. A short screen recording showing the exact flow is even better — especially for bugs involving animations, timing, or multi-step interactions.
Ybug makes this effortless: click the feedback button, annotate the screenshot, describe the issue, and hit send. The tool captures the technical context (browser, console, URL) automatically.
6. Set severity and priority honestly
Not every bug is critical. Mislabelling a cosmetic issue as a blocker erodes trust and messes up sprint planning. Use a consistent scale:
| Severity | Meaning | Example |
| Critical | System is down or core feature is unusable for all users. | Payment gateway returns 500 for all transactions. |
| Major | Important feature is broken, but there may be a workaround. | Search filters don't persist after page refresh. |
| Minor | Something works incorrectly but doesn't block users. | Date picker shows wrong month name on Firefox. |
| Trivial | Cosmetic issue with no functional impact. | Footer text is misaligned by 2px on tablet view. |
7. Keep the tone professional
"This is TERRIBLE and clearly nobody tested this!!!" doesn't help anyone move faster. The developer didn't plant the bug on purpose — you're both on the same team. Stick to factual, respectful language. A bug report is a technical document, not a complaint form.
Most teams don't have a bug quality problem — they have a communication problem. A clear report with a screenshot and reproduction steps can cut resolution time in half.
Bug report template (copy & use) 📋
Here's a ready-to-use bug report template you can paste into Jira, Trello, Asana, GitHub, or any issue tracker. It works equally well as a bug ticket template, a bug description template, or a website bug report template — customize the fields to match your team's workflow:
| Field | Your input |
| Title | [What + Where + When — e.g. "Search returns 0 results for valid queries on /products page"] |
| Reporter | [Your name] |
| Date | [YYYY-MM-DD] |
| Environment | [OS, browser + version, device, app version / build] |
| URL / screen | [Exact URL or screen name where the bug occurs] |
| Steps to reproduce |
1. … 2. … 3. … |
| Expected result | [What should happen] |
| Actual result | [What actually happens — include error messages verbatim] |
| Severity | [Critical / Major / Minor / Trivial] |
| Priority | [High / Medium / Low] |
| Attachments | [Screenshot, screen recording, console log] |
| Additional notes | [Frequency, workarounds, related tickets, theories] |
This same structure also works as a software bug report template or a bug reporting template — the key is using it consistently so no critical info gets missed.
Sample bug report examples: good vs. bad 🎯
❌ Bad bug report:
"The login doesn't work. It's been broken for days. Please fix ASAP!!!"
No environment. No steps. No evidence. The developer has nothing to work with — and the emotional tone makes collaboration harder. This is a typical bug report sample that gets bounced back immediately.
✅ Good bug report:
| Title | Login fails with "Invalid credentials" for SSO users on Chrome 120 |
| Environment | macOS 14.2, Chrome 120.0.6099.129, Production (app.example.com) |
| Steps to reproduce |
1. Go to app.example.com/login 2. Click "Sign in with Google" 3. Authenticate with a valid corporate SSO account 4. Observe error on redirect |
| Expected result | User is redirected to the dashboard after SSO authentication. |
| Actual result | "Invalid credentials" error displayed. User stays on login page. Console: 401 Unauthorized from /api/auth/callback. |
| Severity / priority | Critical / High — all SSO users are locked out of the app. |
| Attachments | [screenshot_login_error.png, console_network_log.har] |
| Additional notes | Reproducible 100% of the time. Non-SSO (email/password) login works fine. Started after the 2.4.1 deploy. |
The good bug report example gives the developer a clear path to reproduce, investigate, and fix — including a likely trigger (the 2.4.1 deploy). No guesswork. No follow-up questions needed.
What are the most common bug reporting mistakes?
Vague titles. "Something's wrong" forces the developer to open and read the entire ticket before even understanding the problem. A specific title saves everyone time — especially during bug triage when the team is prioritizing 20+ issues across bug tracking tools like Jira or Trello.
Missing or incomplete reproduction steps. This is the #1 reason bug reports get bounced back with "cannot reproduce." Every step matters — including pre-conditions like which user role you're logged in as.
Bundling multiple bugs. One report should describe one problem. Mixing issues leads to partial fixes, confused statuses, and tickets that never fully close.
Skipping environment details. A bug that only appears on Safari mobile is invisible to a developer testing on Chrome desktop. Always include browser, OS, device type, and app version.
Describing what didn't happen instead of what did. "The button doesn't work" tells the developer nothing. "Clicking the 'Submit' button triggers no response — no loading spinner, no network request, no error" is actionable.
How can a bug reporting tool speed things up?
Writing thorough bug reports manually is slow — especially during QA testing or user acceptance testing sessions, when you're filing dozens of issues in a single afternoon. This is where dedicated bug reporting tools and customer feedback tools make a real difference.
A good tool sits directly on your website or app as a feedback widget. When someone spots an issue — whether it's an internal tester, a client, or an end user — they click a button, annotate a screenshot, and describe the problem. The tool automatically captures the browser, OS, screen size, current page URL, JavaScript console logs, and often a screen recording. No manual data gathering. No switching between apps.
The best tools also push reports directly into your project management software — Jira, Trello, Asana, GitHub, ClickUp, Slack, and others — so the issue arrives as a ready-to-triage ticket with technical metadata, visual proof, and the reporter's description. That means less time on admin and more time on actual fixes.
Ybug is one such tool. It offers all of the above, with setup in under 5 minutes and integrations with the most popular project management platforms. You can start a free trial to see how it fits your workflow.
Quick checklist: how to write a good bug report
Before you hit "Submit" on your next software bug report, run through this list:
- Title: Does it answer What? Where? When?
- Environment: Did you include OS, browser version, device, and app/build version?
- Steps to reproduce: Could someone who's never used the product follow them?
- Expected vs. actual result: Are both clearly stated?
- Severity & priority: Are they set honestly — not everything is Critical?
- Visual proof: Is there an annotated screenshot or screen recording attached?
- One bug per report: Are you filing a single, focused issue?
- Professional tone: Are you stating facts, not frustrations?
If you can check every box, you've just learned how to write a good bug report. Your developers will thank you.
