Bug report key facts
- Use a title that states the visible failure and context.
- Start reproduction from a known state.
- Separate expected and actual behavior.
- Include exact versions, times, and identifiers.
- Remove passwords, tokens, personal data, and irrelevant logs.
- Label suspected causes as hypotheses.
Copyable Markdown bug report template
# Bug report: [Short observable problem]
## Summary
[What happened, where, and the user impact.]
## Environment
- **Product/version:** [Version or commit]
- **Operating system:** [OS and version]
- **Browser/device:** [Browser and version or device]
- **Account/role:** [Relevant permissions]
- **Environment:** Production/Staging/Development
## Preconditions
- [Required state, data, flag, or configuration]
## Steps to reproduce
1. [Start from a known state]
2. [Perform one action]
3. [Perform the next action]
## Expected result
[What should happen.]
## Actual result
[What happens instead, including exact error text.]
## Reproducibility
- **Frequency:** Always/Intermittent/Once
- **First observed:** YYYY-MM-DD HH:MM [time zone]
- **Regression:** Yes/No/Unknown
## Impact and severity
- **Affected users:** [Scope]
- **Severity:** Critical/High/Medium/Low
- **Workaround:** [Workaround or “None known”]
## Evidence
- **Screenshot or recording:** [Link]
- **Logs:** [Excerpt and timestamp]
- **Request/correlation ID:** [ID]
```text
Paste the smallest relevant log excerpt here.
Remove secrets and personal data.
```
## Acceptance criteria
- [ ] The steps no longer reproduce the error.
- [ ] A regression test covers the failure.
- [ ] Monitoring or documentation is updated if required.
Severity is not priority
Severity describes technical or user impact. Priority describes when the organization should act. Keep them separate so a high-impact but rare issue is not confused with a lower-impact issue that blocks a current release.
Make reproduction reliable
Reduce the case to the fewest steps that still fail. State required data, flags, permissions, locale, network conditions, and account state. If the bug is intermittent, record how many attempts failed and the relevant times.
Use exact error text, but do not paste an entire log file. Include the shortest excerpt that covers the failure and nearby context. Store large evidence in the approved system and link it with access controls.
Verify the fix
Repeat the original steps in the affected environment, test a nearby non-failing case, and add an automated regression test when practical. A fix is not fully verified if it only removes the visible error while losing data or producing an incorrect result elsewhere.
Completed bug report example
Title: Checkout remains on the payment screen after a successful card charge
Environment: Production, app 4.8.2, macOS 15.6, Safari 19.0, customer role
Steps: Add an in-stock item, proceed to checkout, pay with a saved card, then wait for confirmation. The payment provider records a successful charge, but the browser remains on the payment step and shows “Processing”. The order appears only after the page is refreshed.
This example is useful because it states the visible failure, the environment, the expected confirmation and the evidence needed to investigate. It does not declare a timeout or webhook defect before that cause is verified.
What to include in a bug report
| Field | Useful detail |
|---|---|
| Title | Visible problem plus the context in which it occurs |
| Environment | Product version, OS, browser, account role and deployment |
| Steps | Minimum sequence from a known starting state |
| Expected result | Observable correct outcome |
| Actual result | Exact failure, including error text and frequency |
| Evidence | Redacted screenshot, recording, log excerpt or request ID |
| Impact | Who is affected and what they cannot complete |
Bug report FAQ
Should a bug report include the suspected cause?
Only as a labeled hypothesis. Keep observed behavior separate so investigators can test other explanations.
How much log data should I paste?
Use the smallest relevant excerpt with timestamps and identifiers. Remove secrets and personal data. Link to protected logs when access control is required.
What makes a bug reproducible?
Another person should be able to start from the stated conditions, perform the numbered actions and observe the same result. Record frequency when the problem is intermittent.