How to Write a Clear Bug Report

A clear bug report gives another person enough information to understand the failure, reproduce it, and investigate. Start with a specific summary, list numbered steps with the setup and inputs that matter, separate expected from actual behavior, and include relevant environment details and evidence. Describe uncertainty honestly; do not present a guess as a confirmed cause.

Mozilla’s Bug Writing Guidelines call reproduction steps the most important part of a report. The practical test is simple: could a developer follow your steps and reach the same state without asking what you meant?

1. Start with a specific summary

Write a short, searchable description of the observable failure and the condition under which it occurs. “Checkout fails after applying a discount code” is more useful than “Checkout is broken.” Avoid putting a proposed cause in the summary unless it is known.

Keep one report focused on one issue. If two failures have different steps or outcomes, separate them so they can be investigated and tracked independently. Follow the project’s issue form if it asks for a particular title format or fields.

2. Include the details that make it reproducible

Use numbered steps. Begin with the state the reporter needs to be in, then provide each action and any exact input that matters. Include account type, permissions, feature flags, sample data, or configuration only when they affect the result. Replace private or production data with safe examples where possible.

Sign in as a standard user and open the Billing page.
Choose “Add payment method.”
Enter the supplied test card number and select Save.

That example is only useful if the project has a defined test card and the steps accurately describe the observed issue. Do not invent inputs, claim to have reproduced a failure when you have not, or omit a prerequisite that changes what happens.

3. Separate expected and actual results

State the intended outcome and the observed outcome in separate fields. Describe what you saw: the message, page state, returned value, or action that did not happen. If there is exact error text, include it verbatim and identify where it appeared. Avoid conclusions such as “the database is corrupt” unless you have evidence for that diagnosis.

Field	What to write
Expected	What should have happened from the user’s perspective.
Actual	What happened instead, including relevant error text or visible state.

4. Add relevant environment and frequency

Environment details help distinguish a general defect from one tied to a particular version, device, browser, or network. Include only details that could plausibly change the outcome; a long inventory of unrelated system information makes the report harder to scan.

Application, service, or package version, including build number when available.
Operating system and device, if relevant.
Browser name and version for browser behavior.
Connection type or network conditions when they matter.
Account role, configuration, or relevant feature setting.
Frequency: every time, intermittent, happened once, or not reproduced again.

For an intermittent problem, give the observed frequency and conditions you noticed. “Happened twice in five attempts after returning from sleep” is more actionable than “sometimes.” If you cannot reproduce it now, say so and retain the original steps as accurately as you can.

5. Attach evidence that clarifies the failure

A screenshot, short recording, log excerpt, or minimal test case can make a report easier to understand. Use the smallest evidence that shows the issue and include context such as the action immediately before the failure. For browser bugs, MDN recommends a minimal test case when possible, checking browser differences where useful, and including the browser version and relevant screenshots.

Crop screenshots to the relevant area while preserving enough context to interpret it.
Include the browser or application version when the issue depends on it.
Redact tokens, passwords, personal information, and private customer data before sharing.
Keep logs focused around the failure and preserve timestamps or request identifiers if they help investigation.
Do not attach a large dump when a short reproduction case demonstrates the problem.

6. Use this bug report template

This template combines common guidance from Mozilla, Atlassian’s Jira bug report template, and MDN’s browser bug reporting guidance. It is not a universal required form: use the receiving project’s own fields when it provides them.

Summary: [Product or feature] [observable failure] when [important condition]

Environment: [app and version], [operating system/device], [browser and version if relevant]
Frequency: [every time / sometimes / once so far / unable to reproduce again]

Steps to reproduce:
1. [Starting state or setup]
2. [Action and exact input]
3. [Next action]

Expected result:
[What should have happened]

Actual result:
[What happened instead; include exact error text if available]

Evidence:
[Minimal test case, screenshot, relevant log, or recording; redact sensitive data]

Notes:
[Relevant condition or recent change. Label uncertainty clearly.]

7. Capture a useful browser screenshot

When the visible browser state is part of the failure, a screenshot can show the layout, message, or missing element more clearly than a written description alone. Capture the state that demonstrates the issue, and explain which step led to it. A screenshot is evidence of what was visible; it does not by itself prove the cause.

You can capture evidence manually with your browser’s screenshot feature or use a browser automation tool already available in your project. Keep the target URL and any account or test data safe to share, and check that the image does not expose private information.

Or skip the browser setup

If you need a screenshot for a browser bug report, ScreenshotNeo provides a one-request website screenshot API. See the API documentation for its options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. These features can help capture a page state, but a screenshot still needs reproducible steps and an honest description of what happened.

8. Troubleshoot reports that are hard to act on

Problem	Why it slows investigation	Fix
“It is broken” with no steps	The reader cannot reach the failing state.	Add numbered actions, setup, and exact inputs.
Expected and actual results are mixed together	The discrepancy is unclear.	Write one short expected statement and one observed statement.
A suspected cause is stated as fact	It can send investigation toward an unsupported explanation.	Describe observations separately; label theories as unconfirmed notes.
No versions or platform details	The issue may depend on a particular environment.	Add relevant app, OS, device, or browser versions.
Intermittent issue reported as consistent	Others may fail to reproduce it and lose useful context.	State frequency, conditions, and whether you can reproduce it now.
Screenshot contains sensitive data	Sharing may expose credentials or personal information.	Redact secrets and private data; share only the relevant evidence.
Evidence is too large or unrelated	The key behavior is difficult to find.	Provide a minimal case or focused screenshot/log excerpt.

9. Keep the report useful after filing

Check the project’s reporting instructions and required fields.
Search for an existing report when the project asks reporters to avoid duplicates.
Submit one issue per distinct failure and link related reports if needed.
Respond to follow-up questions with missing setup, versions, or evidence.
Update the report if you learn that the steps or environment were incomplete.

Frequently asked questions

Should I include a severity rating?

Include one when the issue form asks for it. Follow the project’s definitions; otherwise describe the user impact clearly and let maintainers assign severity.

What if I do not know the technical cause?

That is fine. Report the observable behavior and distinguish any possible explanation from confirmed facts.

Should every bug report include a screenshot?

No. Add one when visual evidence makes the failure easier to understand. Some problems are better demonstrated by steps, a minimal test case, or a focused log excerpt.

Should I report several symptoms together?

Use one report when the symptoms belong to the same failure and share a reproduction path. Split independent problems so each can be investigated on its own.

Sources and further guidance

Mozilla Bug Writing Guidelines cover clear summaries, separate reports, reproduction steps, expected and actual results, and environment details.
Atlassian’s bug report template provides structured fields including severity, environment, frequency, and reproducibility.
MDN: When and how to file bugs with browsers discusses minimal test cases, browser versions, expected versus actual behavior, and useful evidence.
PLOS Computational Biology: Ten simple rules for reporting a bug is a practical guide to communicating software defects.