How to Write a Good Bug Report (With Templates and Examples)

Why your bug reports get ignored

Most bug reports fail for the same reason: they describe the symptom but not the situation. "The button doesn't work" tells a developer nothing. Which button? What page? What did you expect? What happened instead?

A good bug report answers one question: Can the developer reproduce this without asking you anything?

If the answer is yes, your report will get fixed fast. If it's no, it joins the pile of tickets that sit unresolved for weeks while developers chase missing context.

The anatomy of a great bug report

Every effective bug report has five parts:

1. A clear, specific title

Bad: "Bug on dashboard" Good: "Export to CSV returns 500 error when date filter is set to custom range"

The title should tell a developer what's broken and where — without opening the ticket.

2. Steps to reproduce

This is the most important part. Write the exact steps someone else needs to follow to see the bug:

1. Go to the Analytics dashboard 2. Set the date filter to "Custom range" 3. Select March 1 – March 15, 2026 4. Click "Export to CSV" 5. Observe the 500 error page

Be specific. "Go to the dashboard" is vague. "Go to /dashboard/analytics" is precise.

3. Expected behavior

What *should* have happened? This helps developers distinguish bugs from intended behavior.

Example: "A CSV file containing the filtered analytics data should download."

4. Actual behavior

What *actually* happened?

Example: "The page shows a 500 Internal Server Error. No file is downloaded. The error appeared immediately after clicking Export."

5. Environment and context

Include anything that might affect reproducibility:

• URL: The exact page URL
• Browser: Chrome 124, Safari 18, etc.
• OS: macOS 15.1, Windows 11, etc.
• Account: Your username or role (some bugs are role-specific)
• Console errors: Any red errors in the browser console
• Network state: Was there a failed API call?

Bug report template

Here's a template you can copy:

Title: [Component] — [What's broken] when [condition]

Steps to reproduce: 1. [Step 1] 2. [Step 2] 3. [Step 3]

Expected behavior: [What should happen]

Actual behavior: [What actually happens]

Environment:

• URL: [page URL]
• Browser: [name + version]
• OS: [name + version]
• Console errors: [yes/no — paste if yes]

Screenshot: [Attach screenshot or screen recording]

Common mistakes to avoid

Being too vague

• Bad: "The page is slow"
• Good: "The /dashboard page takes 12 seconds to load on first visit. Subsequent loads are under 2 seconds. Tested on Chrome 124 with a cleared cache."

Skipping reproduction steps

If you can't reproduce it yourself, say so: "I saw this once and couldn't reproduce it. Here's what I was doing when it happened." An intermittent bug with context is still useful.

Assuming the developer sees what you see

Your local state matters. You might be logged in as an admin, using a specific browser, with certain feature flags enabled. A developer working locally might have none of these. Always include context.

Filing duplicates

Before creating a new ticket, search for existing reports. Use different keywords — the same bug might be described as "login fails," "authentication error," or "can't sign in."

Mixing multiple bugs in one report

One bug per ticket. If you found three issues, file three reports. This makes triage, assignment, and resolution much cleaner.

Examples of real bug reports

Example 1: Good report

Title: Invitation email shows raw HTML when org name contains an ampersand

Steps to reproduce: 1. Create an organization named "Smith & Co" 2. Go to Settings > Team > Invite member 3. Enter an email and send the invitation 4. Check the received email

Expected: The email renders normally with "Smith & Co" in the greeting.

Actual: The email shows "Smith & Co" — the ampersand is double-escaped.

Environment: Tested in Gmail (web) and Apple Mail. Both show the same issue.

Example 2: Good report (with uncertainty)

Title: Dashboard chart shows zero values for yesterday's data intermittently

Steps to reproduce: 1. Go to /dashboard/analytics 2. View the "Daily active users" chart 3. Note that yesterday's bar shows 0 4. Refresh the page — sometimes it shows the correct value (~1,200)

Expected: Yesterday's bar consistently shows the correct value.

Actual: Roughly 1 in 3 page loads show 0 for yesterday. Might be a caching or timezone issue.

Environment: Chrome 124, macOS. Happening since ~March 28.

How AI is changing bug reporting

What if you didn't have to write any of this manually?

Modern tools like JAX use AI to capture context automatically — screenshots, console errors, network requests, and page metadata — and turn a plain-English description into a structured engineering ticket.

Instead of filling out a template, you tell the AI "the export button gives a 500 when I filter by date range" and it creates the full report for you, complete with all the technical context a developer needs.

It even checks for duplicate tickets before creating a new one.

For teams with non-technical reporters — PMs, stakeholders, clients — this eliminates the training problem entirely. The AI handles the translation from "something looks wrong" to a ticket the developer can act on.

Checklist before you submit

• [ ] Title is specific (not "bug" or "broken")
• [ ] Steps to reproduce are numbered and precise
• [ ] Expected and actual behavior are clearly stated
• [ ] Environment info is included (browser, OS, URL)
• [ ] Screenshot or recording is attached
• [ ] You searched for duplicates first
• [ ] One bug per ticket

Good bug reports save everyone time. A 2-minute investment in writing a clear report prevents hours of back-and-forth later.

Further reading: Learn why bug reports still suck in 2026 or see our comparison of the best bug reporting tools.