Back to all posts
Quality7 min read·November 8, 2026

How to Write a Bug Report Developers Can Act On

TB
ThynkBlox Team
Engineering

A good bug report states what you did, what you expected, what actually happened, where it happened, how often it happens and what evidence you have. Report one problem per report and include enough detail for a developer to see the problem for themselves without asking you. If they can reproduce it, they can usually fix it. If they cannot, the report tends to sit in the queue.

Why does the quality of a bug report matter?

Developers fix what they can see. A vague report starts a round of questions: which page, which account, which browser, did it happen again. Each round adds delay, and some details are forgotten by the time anyone asks.

A clear report turns a complaint into a task someone can do. It also makes it easier to decide what to fix first, how to test the fix and how to confirm the problem has gone. If you are checking a new release before you accept it, a user acceptance testing checklist shows where bug reporting fits into sign-off.

What should a bug report include?

Use the same structure every time. Consistent reports are faster to read and harder to leave half finished.

FieldWhat to writeExample (illustrative)
TitleThe problem and where it happens, in one lineInvoice PDF download fails for invoices with discounts
What you didNumbered steps from a known starting point1. Sign in as an admin. 2. Open Invoices. 3. Click Download on an invoice with a discount
What you expectedThe result that should have happenedThe PDF downloads
What happenedThe actual result, including any error text copied exactlyA spinner shows, then "Something went wrong"
WhereEnvironment, device, browser or app version, account or roleProduction, Windows laptop, Chrome, admin role
How oftenEvery time, sometimes, or once, and since when if knownEvery time on discounted invoices; full-price invoices work
EvidenceScreenshots, a screen recording, error messages, record referencesScreen recording attached; invoice reference included
ImpactWho is affected and what they cannot doFinance cannot send discounted invoices to customers

You can copy this template into whatever tracker your team uses:

  • Title:
  • Steps to reproduce:
  • Expected result:
  • Actual result:
  • Environment and account:
  • Frequency:
  • Evidence:
  • Impact and suggested severity:

What does a weak report look like next to a strong one?

Here is an illustrative example of the same problem reported two ways.

Weak report

> Title: Checkout broken

>

> Checkout doesn't work again. Customers are complaining. Please fix ASAP.

A developer reading this does not know which step fails, for whom, on what device, or what "doesn't work" means. "Again" suggests history, but there is no link to it. They have to start by asking questions.

Strong report

> Title: Payment step shows blank screen on mobile Safari after applying a promo code

>

> Steps to reproduce:

> 1. On an iPhone using Safari, open the shop and add any item to the cart.

> 2. Go to checkout and apply the promo code used in the attached recording.

> 3. Tap Continue to payment.

>

> Expected: The payment form loads with the discounted total.

>

> Actual: The screen goes blank. No error message appears. Refreshing returns to the cart.

>

> Where: Production site, iPhone, Safari. Tested on a desktop browser with the same code: works.

>

> How often: Every time with a promo code on mobile Safari. Without a promo code, checkout works.

>

> Evidence: Screen recording attached. Two customer support messages describing the same behaviour, linked.

>

> Impact: Mobile customers using promotions cannot pay. Suggested severity: high.

The strong version narrows the problem to a specific condition, shows what works as well as what fails, and explains the business effect. A developer can usually start investigating straight away.

How do you take screenshots and recordings that help?

Evidence answers the question "what did you see?" more precisely than a description.

  • Capture the whole screen or window, not just the error box. The address bar, page layout and surrounding content often explain the context.
  • Use a short screen recording when the bug depends on a sequence of steps or a timing problem. Start a few steps before the failure.
  • Copy error text as text as well as showing it in an image, so it can be searched.
  • Mark the problem area with a simple box or arrow if the screen is busy.
  • Remove or blur sensitive information such as passwords, card details and personal customer data before attaching anything. Share a record reference instead of the record itself. Our guide to data security in modern applications covers why this matters.

What environment details should you include?

Many bugs only appear in certain conditions, so record them:

  • Which environment: production, staging or a test environment. If you are unsure of the difference, see dev, staging and production environments explained.
  • Device and operating system: phone, tablet or computer, and the system it runs.
  • Browser or app version: the browser name, or the installed app version shown in its settings.
  • Account and role: which type of user you were signed in as. Permissions often change what a person sees. Do not share your password; give the account name or a test account.
  • Time it happened: an approximate time helps developers find matching entries in the system's logs.
  • Data involved: the specific order, invoice or record reference, if the bug relates to particular data.

How do you keep to one issue per report?

Each report should describe one problem with one expected fix. When several problems share a report, one gets fixed, the report is closed, and the others are lost. It also becomes hard to say whether the report is done.

Practical rules:

  • If you notice a second problem while reproducing the first, file it separately and mention the link between them.
  • If the same problem appears on several pages, one report is fine, with each location listed.
  • Search existing reports before filing. If the problem is already reported, add your evidence there instead of creating a duplicate.
  • Keep requests for new behaviour separate. "The button should also export to spreadsheet" is a feature request, not a bug, and may be priced as a change request.

What is the difference between severity and priority?

These two words are often used as if they meant the same thing. They do not.

Severity describes how bad the problem is: how much it damages the product or the user's ability to do something. Priority describes how soon the team should fix it, given everything else that needs doing.

The person reporting usually suggests severity. The product owner or whoever manages the work usually sets priority, because it depends on business context.

Situation (illustrative)SeverityPriorityWhy
Customers cannot complete paymentHighHighSerious damage and directly affects revenue
A rarely used admin report crashesHighLow or mediumSerious failure, but few people affected and a workaround exists
Company name misspelt on the home pageLowHighMinor technical problem, but highly visible
Slight misalignment on a settings screenLowLowCosmetic and rarely seen

When reporting, describe the impact honestly and suggest a severity. Avoid marking everything urgent. If every report is top priority, the label stops carrying information and the genuinely urgent issues wait in line with the rest. Your software maintenance and support agreement may define severity levels and the response expected for each, so use the same terms it does.

What are common bug reporting mistakes?

Describing the conclusion rather than the observation. "The database is broken" is a guess. "Saving a customer record shows an error" is an observation developers can check.

Leaving out what you expected. Sometimes the software is behaving as designed and the design is the problem. Stating your expectation makes that visible. Clear acceptance criteria reduce these disagreements.

Skipping the steps because they feel obvious. They are obvious to you because you did them.

Reporting by chat or phone only. Messages scroll away. Put the report in the tracker and link to the conversation if needed.

Bundling feedback into one long document. A list of twenty observations is hard to assign, track and close. Split it into individual reports.

Not confirming the fix. When a fix is released, repeat your original steps and confirm the result, or reopen the report with new evidence.

When does this format not apply?

Security vulnerabilities should not go into a widely visible tracker. Report them privately to the agreed contact so the details are not exposed before a fix is ready. Active outages that stop the business need a call or alert through your agreed escalation route first, with a written report to follow. A security incident response plan should spell out that route.

Frequently asked questions

What if I cannot reproduce the bug?

Report it anyway, and say so. Include the time it happened, what you were doing, the account used and any evidence. Mark the frequency as "once" or "intermittent". Several such reports together often reveal a pattern.

How much detail is too much?

Keep the report focused on one problem, but do not trim facts to make it shorter. Steps, environment and evidence are rarely too much. Opinions about the cause, or unrelated observations, belong elsewhere.

Should non-technical staff write bug reports?

Yes. The people using the software every day often see problems first. A shared template means anyone can produce a report developers can act on, without technical knowledge.

Who decides when a bug gets fixed?

Usually the product owner or project lead sets priority, based on severity, business impact and other planned work. The reporter's job is to describe the problem and its impact clearly enough for that decision to be made well.


*Want a development partner with a clear process for reporting, prioritising and fixing issues? Start a conversation →*

Ready to build?

Let's turn these ideas into your next product.

Start your project