How to Write a Bug Report

A bug report is not just a note that something is broken. It is a working document that helps another person reproduce the issue, understand the impact, and decide what to do next. The best bug reports save time for developers, testers, support staff, and product managers because they turn a vague complaint into a clear investigation path.

If you have ever written “it doesn?t work” and then had to answer five follow-up questions, you already know the problem. A strong bug report anticipates those questions. It includes the right context, the exact steps, the expected result, the actual result, and enough supporting detail to let someone else verify the issue without guessing.

What a good bug report does

A useful bug report has three jobs:

Explain what failed.
Show how to reproduce it.
Make it easy to judge priority and severity.

That sounds simple, but each part matters. If the reproduction steps are missing, the report becomes hard to trust. If the impact is unclear, the issue might get triaged incorrectly. If the report is overloaded with irrelevant detail, the important signal gets lost.

A good report is specific, brief, and complete. Those goals can conflict, so the skill is deciding which details matter and which ones are noise.

Start with the basics

Before you write the narrative, capture the facts that establish the environment. These are the first questions a developer or tester will ask.

Field	What to include	Why it matters
Title	A short summary of the failure	Helps triage and search
Environment	App, version, browser, OS, device, account type	Narrows the cause
Steps to reproduce	Ordered actions that trigger the bug	Lets others verify it
Expected result	What should have happened	Defines the contract
Actual result	What actually happened	Describes the failure
Evidence	Screenshot, video, logs, error text	Speeds diagnosis
Impact	Who is affected and how often	Helps prioritize

If you are not sure about a detail, say so. A report that clearly marks an unknown is better than one that invents certainty.

Write a title that can stand alone

The title should be readable in a ticket list without opening the issue. Good titles usually follow this pattern:

[Area] action causes failure under condition
App crashes when uploading a file larger than 50 MB
Checkout button does nothing in Safari on iPhone

Avoid titles like “Bug” or “Doesn?t work.” Those do not communicate the scope or the trigger. You want the title to hint at both the symptom and the context.

A strong title often includes the feature, the action, and the consequence. That makes it easier to group duplicate reports and route the issue to the right team.

Describe the environment precisely

Many bugs only happen in a particular configuration. That is why environment details are not optional. Include the following when relevant:

Application name and build number
Browser and version
Operating system and version
Device model and screen size
User role or permission level
Test data or account type
Network conditions if they matter

If the issue only appears for one account, one browser, or one region, state that clearly. A developer cannot reproduce a hidden dependency if the report leaves it out.

Make the steps reproducible

The reproduction steps are the core of the report. Write them as a numbered sequence and make each step atomic. One step should describe one action.

Good example:

Open the app and sign in as a standard user.
Go to Settings > Notifications.
Turn off email notifications.
Click Save.
Refresh the page.

Bad example:

Open the app, sign in, change the settings, save, refresh, and notice it is broken.

The second version compresses too much. If the bug depends on one exact click or a hidden transition, the compressed version is easy to misread. A good rule is that another person should be able to follow the steps without asking what you meant.

If the bug is intermittent, say so. Include how often it happens and whether it needs retries, specific timing, or a certain sequence of actions.

Separate expected and actual results

This is where many reports get vague. The expected result should describe the intended behavior, not your opinion about it. The actual result should describe what happened, not the conclusion you drew about why it happened.

For example:

Expected: The file uploads successfully and appears in the attachment list.
Actual: The upload fails with a 500 Internal Server Error message.

That distinction matters because it keeps the report factual. It also helps the team decide whether the issue is a crash, validation problem, backend failure, or UI mismatch.

Add evidence that helps diagnosis

Screenshots are useful, but they are rarely enough on their own. The most effective evidence often includes one or more of these:

Screenshot of the visible failure
Screen recording showing the exact sequence
Console errors from the browser
Server logs or application logs
Request IDs or trace IDs
Error messages copied verbatim

If there is an error code, copy it exactly. If there is a stack trace, include the relevant part. If the bug is in the browser, inspect the console and network tab before you file the report. Small pieces of evidence often cut debugging time dramatically.

Explain impact without exaggeration

Severity and priority are not the same thing, and a good bug report helps the team judge both.

Severity is how bad the defect is from a technical or functional perspective.
Priority is how urgently it should be fixed relative to other work.

A typo on the homepage may be low severity but high priority if it affects a launch page. A crash in a rarely used admin path may be high severity but lower priority if it affects few users. Your job is not to decide the final ranking, but to explain the impact clearly enough that someone else can.

Useful impact details include:

How many users are affected
Whether the bug blocks a key flow
Whether there is a workaround
Whether it affects revenue, data integrity, or trust
Whether it is new or a regression

Keep your language factual

A bug report should read like a reliable account, not a rant. That means avoiding loaded language such as “terrible,” “ridiculous,” or “completely broken” unless you are quoting a user. Those words do not help the investigator.

Use direct statements instead:

“The checkout button does not respond after the address form is completed.”
“The page displays an uncaught exception in the console after submission.”
“The report export generates a blank PDF when filters are applied.”

If a customer report is emotional, you can preserve the essence while rewriting it into objective language.

A practical bug report template

Use this as a starting structure:

## Summary
Short description of the issue.

## Environment
App version:
Browser/OS:
Device:
Account or role:

## Steps to Reproduce
1. ...
2. ...
3. ...

## Expected Result
What should happen.

## Actual Result
What happened instead.

## Evidence
Screenshots, logs, error messages, links.

## Impact
Who is affected, how often, and how serious the problem is.

You do not need to force every ticket into the same shape, but consistency helps teams scan issues quickly. If your organization already has a bug template, follow it closely.

Example of a strong bug report

Summary

The mobile checkout page freezes after selecting Apple Pay on iPhone Safari.

Environment

App version: 3.4.1
Device: iPhone 14
OS: iOS 17.3
Browser: Safari
Account type: Standard customer

Steps to Reproduce

Open the checkout page on an iPhone.
Enter shipping details.
Choose Apple Pay as the payment method.
Tap Pay.

Expected Result

The payment sheet opens and the order completes.

Actual Result

The page becomes unresponsive and the payment sheet never appears.

Evidence

Screen recording of the freeze
Console error: TypeError: undefined is not an object
Request ID: b8f4c21d

Impact

This blocks mobile purchases for affected users and may reduce completed orders on Safari.

That report works because it tells the reader what, where, how, and why it matters.

Common mistakes to avoid

A few patterns make bug reports harder to use:

Writing a title that is too generic
Skipping environment details
Combining multiple bugs into one ticket
Listing unclear or incomplete steps
Guessing at the root cause instead of describing symptoms
Failing to include evidence when it is available
Using “works on my machine” as a dismissal rather than checking the reported environment

One report should usually cover one defect. If you find several issues during testing, separate them unless they are clearly the same underlying problem.

When to ask for more information

Sometimes a bug report is missing a critical detail. Before closing it, ask for the smallest useful clarification:

Which account was used?
Which browser and version?
Can you reproduce it after clearing cache?
Does it happen every time or only sometimes?
Can you attach a screenshot or video?

Good follow-up questions are specific. They help fill the exact gap that blocks reproduction.

Final checklist

Before you submit a bug report, verify that it answers these questions:

What failed?
Where did it fail?
How do you reproduce it?
What should have happened instead?
What actually happened?
What evidence supports the claim?
Why does it matter?

If the report answers those questions clearly, it is probably good enough to move the issue forward.

Closing thought

Writing a bug report is really an exercise in empathy. You are trying to save the next person from repeating your investigation from scratch. The best reports are not the longest ones; they are the ones that reduce uncertainty quickly. When in doubt, be precise, be factual, and make the path to reproduction obvious.