Skip to content
midgeDocs
Bug reportsHow to write a bug report developers can act on
Bug reports

How to write a bug report developers can act on

How to write a bug report that gets fixed: a specific title, exact steps to reproduce, expected vs actual results, environment details and evidence.

To write a bug report developers can act on, reproduce the problem first, then write a specific one-line title, the environment (URL, browser and version, operating system, account), numbered steps to reproduce from a known starting point, the expected result, the actual result with exact error messages, and attach evidence such as a screenshot or recording, console errors and the failing network request. One bug per report.

The test of a good report is simple: could a developer who has never seen the problem make it happen on their own machine, without asking you anything? If yes, the bug will probably be fixed quickly. If they have to come back with questions, every round trip costs a day. If you want the fields as a checklist, copy our bug report template.

1. Reproduce it before you write

Try to make the bug happen a second time. While you do, pay attention to the details that might matter:

  • Which account or role you were using.
  • What data was involved: a specific product, a long name, an empty list, a large file.
  • Which steps are really needed. Remove steps one at a time to find the shortest path.
  • Whether it happens in another browser or in a private window.

If it happens every time, great. If it happens only sometimes, count it: “4 out of 10 tries”. If you cannot reproduce it at all, still report it, and say so clearly.

2. Check whether it is already reported

Search the tracker for the error message, the page name and a few keywords. If you find a match, add your details to it instead of opening a new ticket: your environment, a new way to trigger it, or the fact that it still happens on the latest build. Duplicates split the information across tickets and waste triage time.

3. Write a specific title

The title is often the only thing people read when they triage. Make it describe the problem, not the feature.

Weak titleBetter title
Login brokenSign-in with Google loops back to the login page in Safari
Bug in reportsCSV export of the Sales report is missing rows after 1,000
Page is slowBilling page takes 10+ seconds to load for accounts with many invoices
Error on saveSaving a profile with an emoji in the name returns “Invalid input”

A useful pattern: what is broken, plus when it happens, plus where.

4. Describe the environment

Many bugs only appear in a specific setup. Include:

  • URL of the page where it happened.
  • Browser and version, for example Chrome, Firefox, Safari or Edge with the version number from the About page.
  • Operating system and device.
  • Screen size if it is a layout problem.
  • App version or build, if the app shows one.
  • Account, role or test user, and anything special about it (a trial account, a large organization, a non-English language setting).
  • Time it happened, with time zone, so the team can find it in server logs.

5. Write steps to reproduce

Steps are the core of the report. Good steps:

  • Start from a known state: “Signed in as an admin, on the Dashboard”.
  • Use one action per numbered step.
  • Name the exact data: the product, the file, the text you typed. Never include real passwords or card numbers; use test data.
  • Use the labels shown in the app, in bold or quotes, so the developer finds the same button.
  • End at the moment the bug appears.
1. Sign in as [email protected] (Admin role).
2. Go to Settings, then Team.
3. Click "Invite member".
4. Enter "[email protected]" and choose the role "Viewer".
5. Click "Send invite".

6. Write expected and actual results

Put them next to each other:

Expected: The invite appears in the Pending list and a confirmation toast is shown.
Actual: The dialog closes, no toast is shown, and the Pending list stays empty.
        After reload the invite is still missing.

Describe what you observed, not what you think caused it. “The invite request failed” is a conclusion; “the dialog closed and nothing appeared in the list” is an observation. If you saw an error message, copy it as text, exactly. Developers search their code for that string.

7. Add evidence

Evidence turns a description into proof and often points straight at the cause.

  • Screenshot with the problem area highlighted. Crop out unrelated personal data.
  • Screen recording for anything involving motion, timing or several steps. Keep it short and start just before the problem.
  • Console errors. In web apps, a red error in the browser console is often the most useful clue. See how to export console logs in Chrome.
  • The failing network request. The URL, status code and response body of the API call that failed. See how to capture network traffic in Chrome.
  • A HAR file if the team asks for the whole network session. Follow how to get a HAR file and clean it with the HAR sanitizer first, because HAR files include cookies and tokens.

8. Rate impact honestly

Say how bad it is and how many people it affects. Use your team’s severity scale if there is one. Be honest: if everything is marked critical, nothing is. Mention a workaround if you found one; it changes how urgent the fix is and helps support in the meantime.

9. Keep it to one bug

If you found three problems on the same page, write three reports. Each can then be assigned, fixed, tested and closed on its own. Link them if they seem related.

10. Stay available

After you submit, watch the ticket for questions. When the fix ships, retest with the same steps and confirm. If the bug comes back later, reopen the original ticket or link to it, so the history stays in one place.

Common mistakes

  • Vague titles like “doesn’t work” or “issue with page”.
  • Missing steps, or steps that start in the middle of a flow.
  • Screenshots of error messages instead of the text, which cannot be searched.
  • Several bugs in one ticket.
  • Real secrets in the report: passwords, API keys, session cookies or customer data in screenshots and logs.
  • Emotional language. A calm, factual report gets fixed faster than an angry one.

For side-by-side good and bad reports, see our bug report examples.

Write less, capture more

Most of the effort in a bug report goes into the technical details, and those are also the parts reporters forget. Midge, a free Chrome extension, records your screen or takes a screenshot and attaches those details for you, so you only write the title, the steps and what you expected. Every recording includes console logs, network requests, user actions and device info. Passwords, card numbers, tokens and cookies are redacted in your browser before anything leaves your device. The report is shared as one link that you can paste into whichever tracker your team uses.

Frequently asked questions

What are the most important parts of a bug report?

Steps to reproduce, the expected result and the actual result. With those three, a developer can usually see the problem for themselves. Environment details and evidence such as screenshots and console errors make it faster.

How long should a bug report be?

As short as possible while still complete. Most good reports fit on one screen: a one-line title, a short summary, five to ten steps, expected and actual results, and attachments.

What if I can't reproduce the bug?

Report it anyway and say so. Describe exactly what you were doing, when it happened, and attach any evidence you have, such as a screenshot or console error. Mark the frequency as happened once.

Should I include my opinion about the cause?

Keep observations and guesses separate. Write what you saw in the main fields, and if you have a theory, add it in a notes section labeled as a guess.