What is a bug report?

A bug report is a written record describing unexpected software behaviour, the steps that trigger it, the actual result, and the expected result. It lives in a tracker such as GitHub Issues or Jira so a developer can reproduce the defect, assign a fix, and verify it later without re-asking for context.

What should a bug report include?

Include the product version, environment, steps to reproduce, actual versus expected output, and a minimal test case or file. Add the commit hash or release tag when known. Missing version or environment data is the most common reason a developer cannot reproduce a report and closes it as invalid.

How do you write steps to reproduce?

Number each action in the order you performed it, starting from a clean state. Use exact menu names, URLs, or commands. For example, “POST /api/v1/orders with an empty customer_id returns HTTP 500” is reproducible; “it sometimes breaks” is not. State what you saw and what you expected.

What is a minimal reproducible example?

It is the smallest input, query, or code snippet that still triggers the defect, with everything unrelated removed. In code projects, a failing unit test is ideal. A minimal example lets a developer isolate the cause in minutes instead of first stripping irrelevant configuration or data from a full application dump.

Why do bug reports get ignored or bounced back?

Reports fail when they describe symptoms without reproduction, omit the environment, or mix multiple defects into one ticket. Developers also bounce reports that are actually feature requests or support questions. Keep one defect per ticket, state severity honestly, and answer follow-up questions within the same thread.

How do you choose severity and priority?

Severity is the technical impact: data loss, crash, or security hole ranks higher than a cosmetic misalignment. Priority is business urgency and is set with a product owner. Marking every report “urgent” erodes trust; state which user flow is blocked and how many users or transactions are affected.

Should you include logs, screenshots, or screen recordings?

Yes, but attach them with context. Include the exact log lines around the failure, the request ID, and a screenshot or short recording showing the state before the click. Do not paste a 2,000-line log; trim to the relevant frames and redact tokens, passwords, or customer data first.

How do you verify a fix after it ships?

Re-run the exact reproduction steps against the patched version or staging environment and confirm the expected result now occurs. Ask for the test case name, PR link, or deployment tag. Check that the fix did not introduce a new error in the same flow, then close the ticket with a one-line confirmation.

What is the difference between a bug and a feature request?

A bug is the software behaving contrary to its specification or intended use; a feature request asks for new behaviour. Filing a feature request as a bug wastes a triage cycle. Check the documentation or ask the product owner before reporting, and use the tracker’s feature-request label if one exists.

How do you report a production bug without exposing sensitive data?

Redact customer names, emails, API keys, and tokens before pasting logs or screenshots. Use the tracker’s private attachment or reference an internal log URL instead of copying raw data. If the stack trace contains a database query with parameters, mask the parameter values and note the redaction.

How to Report a Bug So It Gets Fixed Once

To report a bug so it gets fixed once, follow this structure: include a clear title, steps to reproduce, expected vs. actual results, and any error messages or logs. This ensures developers can diagnose and resolve the issue efficiently without back-and-forth.

Key Takeaways

Start with a clear, descriptive title that summarizes the issue in 10 words or fewer.
Include step-by-step instructions to reproduce the bug—developers need exact details to replicate it.
Attach relevant logs, screenshots, or error messages—vague descriptions slow down fixes.
Avoid assumptions; describe the environment (OS, browser, app version) and your user role.
Prioritize bugs with clear impact—developers focus on critical issues first.
Use a bug tracker (like GitHub Issues or Jira) to track progress and avoid lost reports.
Follow up politely if there's no response within a reasonable timeframe.

The stages a bug report goes through, from submission to resolution, showing where your clear details make the biggest difference.

What is a good bug report?

A good bug report is a self-contained document that allows a developer to reproduce, diagnose, and fix the issue without asking you for additional information. It includes a clear title, step-by-step reproduction steps, expected vs. actual behavior, environment details, and any relevant logs or screenshots. Without these, developers waste time guessing what went wrong, delaying fixes.

Why does a clear bug report matter in production?

In production, bugs can cause downtime, data loss, or poor user experiences. A well-structured bug report reduces the time it takes to diagnose and fix issues, minimizing the impact on users. It also helps prioritize critical problems—developers focus on bugs that affect the most users or cause the most severe issues first. Without clear reports, even simple bugs can take days or weeks to resolve, costing you time and money.

When should you report a bug?

You should report a bug as soon as you encounter it, but only if it's reproducible, affects real users, or blocks critical functionality. Avoid reporting minor issues unless they're part of a larger pattern. If the bug is related to a recent change (e.g., a new feature or update), note that explicitly—it helps developers narrow down the cause.

How does a bug report actually work?

A bug report follows a lifecycle: submission, triage, diagnosis, fix, and verification. When you submit a report, it's assigned a priority based on its impact. Developers then reproduce the issue using your steps, investigate the root cause, implement a fix, and verify it works. If your report lacks details, developers may ask for more information, slowing down the process. A clear report ensures the bug is fixed efficiently.

Here is what that timeline looks like in practice when the report is clear enough to reproduce on the first attempt:

The typical elapsed time at each stage of a bug fix when the original report is complete enough to reproduce without follow-up questions.

Step-by-step: How to write a bug report that gets fixed

Follow this checklist to create a bug report that developers can act on immediately:

Title: Write a concise, descriptive title (e.g., "Checkout fails on mobile devices" instead of "Something's wrong").
Steps to reproduce: List exact steps in order, as if you're guiding a developer through the issue. Include browser/device specifics.
Expected vs. actual behavior: Clearly state what should happen and what actually happens.
Environment details: Include OS, browser, app version, and user role (e.g., admin vs. guest).
Attachments: Add screenshots, logs, or error messages. Tools like browser console logs or Docker logs are useful.
Severity: Rate the bug as critical, high, medium, or low based on its impact.

Configuration that matters in a bug report

Not all configurations are equally important, but these are the critical ones developers need to know:

Software versions: Include the exact versions of the app, OS, browser, or libraries (e.g., "Node.js 18.16.0, React 18.2.0").
Hardware/environment: Specify if the issue occurs on mobile, desktop, or a specific cloud provider (e.g., AWS vs. DigitalOcean).
User permissions: Note if the bug only affects certain roles (e.g., only admins can't save changes).
Recent changes: If the bug appeared after a deploy or update, mention it—it helps isolate the cause.

How to verify a bug report works

After submitting a report, check if developers have asked for clarification. If they request additional details, provide them promptly. If the bug is fixed, verify the resolution yourself before marking it as closed. For example, if the issue was a login failure, test the fix by attempting to log in again. If the bug persists, reopen the report with updated details.

Failure modes and how to debug them

Common pitfalls in bug reporting include vague descriptions, missing steps, or irrelevant details. For example:

Vague titles: "App crashes" is useless. Instead, say "App crashes when submitting a form with special characters."
Incomplete steps: If you skip a step, developers can't reproduce the issue. Always start from a clean state.
Irrelevant logs: Attach only the logs related to the bug. A 500MB log dump slows down debugging.
Assumptions about fixes: Don't say "I fixed it by restarting the server"—developers need to understand the root cause.

Cost and operational overhead of poor bug reports

Poor bug reports increase operational overhead in several ways:

Developer time: Chasing unclear reports can take hours or days, delaying fixes and increasing costs.
User impact: Unfixed bugs frustrate users, leading to churn or lost revenue. For example, a checkout bug on an e-commerce site can cost thousands in lost sales.
Technical debt: Ignored bugs accumulate, making the system harder to maintain. Over time, this increases long-term costs.

Security considerations in bug reporting

If the bug involves security (e.g., data leaks, unauthorized access), report it privately and securely. Avoid sharing sensitive details in public bug trackers. Use platforms like HackerOne or your team's internal bug tracker. Never include credentials, API keys, or personal data in reports.

Common mistakes in bug reporting

Here are the most frequent mistakes we see in bug reports:

Overgeneralizing: "It doesn't work" is not helpful. Specify exactly what doesn't work.
Skipping reproduction steps: Developers can't fix what they can't replicate.
Ignoring environment details: A bug on Chrome may not exist on Firefox—always specify the environment.
Assuming the developer knows the context: Explain why the bug matters (e.g., "This breaks 10% of our users' workflows").

A realistic scenario: Reporting a payment failure bug

Imagine you're managing an e-commerce site and users report that payments fail during checkout. Here's how you'd report it effectively:

Title: "Payment gateway rejects transactions on Safari"
Steps to reproduce:
1. Add an item to the cart.
2. Proceed to checkout.
3. Select "Pay with Credit Card" and enter valid test card details (e.g., 4242 4242 4242 4242).
4. Click "Pay Now."
5. The system shows "Payment failed: Invalid card number."
Expected vs. actual:
- Expected: Transaction processes successfully.
- Actual: Error appears, even with valid test card.
Environment:
- Browser: Safari 16.4 (MacOS Ventura)
- Payment gateway: Stripe API (v2023-10-16)
- Backend: Node.js 18.16.0, Express 4.18.2
Attachments:
- Screenshot of the error message.
- Stripe API logs (redacted sensitive data).
- Browser console error: `Uncaught TypeError: Cannot read property 'card' of undefined`.
Severity: High (affects 30% of mobile users).

With this report, developers can quickly identify the issue (likely a missing card validation in Safari) and fix it without additional questions.

Alternatives to manual bug reporting

If you're managing a large team or complex system, consider these alternatives to manual bug reporting:

How different bug reporting methods compare in terms of automation, team size, and use case.

The table below summarizes the trade-offs at a glance:

Method	Best for	Automation	Team size
Manual reports	Small teams, one-off issues	None	1–5 people
Bug trackers	Teams using Jira or GitHub Issues	Partial — triage and assignment	5–50 people
Error monitoring	Production systems with high traffic	High — automatic capture	10+ people
Synthetic testing	Critical paths, regression checks	High — scheduled runs	10+ people

For small projects or one-off issues, manual reports may suffice. For larger teams, bug trackers like GitHub Issues or Jira streamline workflows. For production systems, error monitoring tools like Sentry or Prometheus automatically capture issues. If you're unsure which to use, our team can help you evaluate the best fit for your workflow.

In short

A good bug report saves time for everyone. Start with a clear title, provide step-by-step reproduction instructions, and include environment details and attachments. Avoid vague descriptions or assumptions—developers need exact information to fix the issue quickly. If you're managing a complex system, consider automated tools like error monitoring or bug trackers to reduce manual effort.

People also search for

Need help structuring a bug report or evaluating your current workflow? Our team can help you design a process that works for your team's needs. Get in touch to learn more about how we can support your development process—whether it's debugging, optimizing workflows, or building scalable systems. For a deeper dive into how we handle technical challenges, check out our portfolio.

Frequently asked questions

A bug report is a written record describing unexpected software behaviour, the steps that trigger it, the actual result, and the expected result. It lives in a tracker such as GitHub Issues or Jira so a developer can reproduce the defect, assign a fix, and verify it later without re-asking for context.
Include the product version, environment, steps to reproduce, actual versus expected output, and a minimal test case or file. Add the commit hash or release tag when known. Missing version or environment data is the most common reason a developer cannot reproduce a report and closes it as invalid.
Number each action in the order you performed it, starting from a clean state. Use exact menu names, URLs, or commands. For example, “POST /api/v1/orders with an empty customer_id returns HTTP 500” is reproducible; “it sometimes breaks” is not. State what you saw and what you expected.
It is the smallest input, query, or code snippet that still triggers the defect, with everything unrelated removed. In code projects, a failing unit test is ideal. A minimal example lets a developer isolate the cause in minutes instead of first stripping irrelevant configuration or data from a full application dump.
Reports fail when they describe symptoms without reproduction, omit the environment, or mix multiple defects into one ticket. Developers also bounce reports that are actually feature requests or support questions. Keep one defect per ticket, state severity honestly, and answer follow-up questions within the same thread.
Severity is the technical impact: data loss, crash, or security hole ranks higher than a cosmetic misalignment. Priority is business urgency and is set with a product owner. Marking every report “urgent” erodes trust; state which user flow is blocked and how many users or transactions are affected.
Yes, but attach them with context. Include the exact log lines around the failure, the request ID, and a screenshot or short recording showing the state before the click. Do not paste a 2,000-line log; trim to the relevant frames and redact tokens, passwords, or customer data first.
Re-run the exact reproduction steps against the patched version or staging environment and confirm the expected result now occurs. Ask for the test case name, PR link, or deployment tag. Check that the fix did not introduce a new error in the same flow, then close the ticket with a one-line confirmation.
A bug is the software behaving contrary to its specification or intended use; a feature request asks for new behaviour. Filing a feature request as a bug wastes a triage cycle. Check the documentation or ask the product owner before reporting, and use the tracker’s feature-request label if one exists.
Redact customer names, emails, API keys, and tokens before pasting logs or screenshots. Use the tracker’s private attachment or reference an internal log URL instead of copying raw data. If the stack trace contains a database query with parameters, mask the parameter values and note the redaction.