Writing Bug Reports That Actually Get Fixed

A bad bug report: "The app is broken."

That tells the developer nothing. What's broken? Where? When? What did you expect? What happened instead? The developer now has to ask five questions before they can even start investigating. Multiply this by twenty bug reports a week and a significant portion of engineering time is spent on clarification, not fixing.

A good bug report is a gift. It describes the problem precisely enough that the developer can reproduce it, understand it, and fix it — often without any back-and-forth. The difference isn't writing skill. It's structure.

The Format

Every effective bug report has five parts.

1. Title: What's Wrong, in One Line

The title should describe the symptom, not your diagnosis.

Bad: "Database error" Bad: "Bug in the login system" Good: "Login fails with 500 error when email contains a plus sign" Good: "Order total shows $0 when discount code is applied to a single item"

A developer scanning a list of issues should understand the problem from the title alone. Specific symptoms make issues findable and prevent duplicates.

2. Steps to Reproduce

The most important section. If the developer can't reproduce the bug, they can't fix it. List the exact steps, starting from a known state.

Steps to reproduce:
1. Go to the login page (/login)
2. Enter email: test+user@example.com
3. Enter password: anything
4. Click "Sign In"

Be specific about the starting point. "Go to the login page" is better than "try to log in." The developer knows exactly where to start.

Include the data. If the bug depends on specific input (an email with a plus sign, a product with a zero price, an order with 100 items), include the exact data that triggers it.

Number the steps. This prevents ambiguity about the order of operations and makes it easy to reference a specific step in discussion.

3. Expected Behavior

What should happen when you follow those steps?

Expected: The user is logged in and redirected to the dashboard.

This sounds obvious, but without it, the developer might not know what "correct" looks like — especially for features they didn't build or haven't used recently.

4. Actual Behavior

What actually happens?

Actual: A 500 Internal Server Error page is shown. The user is not logged in.

Be specific. "It doesn't work" is not actual behavior. "A 500 error page appears" is. "The page loads but the order total shows $0.00 instead of $45.99" is. Include error messages, incorrect values, or screenshots of the wrong state.

5. Environment

What system, browser, device, and version were you using?

Environment:
- Browser: Chrome 120 on Windows 11
- App version: 2.4.1 (production)
- Account: test+user@example.com (Standard tier)

Bugs that appear in Chrome but not Firefox are browser-specific. Bugs that appear on mobile but not desktop are responsive design issues. Bugs that only appear for free-tier accounts are permissions issues. The environment narrows the investigation.

The Complete Example

Title: Login fails with 500 error when email contains a plus sign

Steps to reproduce:
1. Go to /login
2. Enter email: test+user@example.com
3. Enter any password
4. Click "Sign In"

Expected: User is logged in and redirected to /dashboard

Actual: 500 Internal Server Error page. User is not logged in.
         Browser console shows: POST /api/auth/login 500

Environment:
- Chrome 120, Windows 11
- Production (app.example.com)
- Reproducible every time

Notes:
- Emails without the "+" sign work normally
- The same email (test+user@example.com) was registered successfully

A developer reading this can reproduce the bug in under a minute, has a strong hypothesis about the cause (the plus sign in the email isn't being handled correctly), and knows the scope (production, all browsers likely, consistent reproduction).

What Makes the Difference

Reproduction Steps Are Everything

A bug that can be reproduced is a bug that can be fixed. A bug that can't be reproduced is a mystery that might get deprioritized indefinitely.

If you can't figure out the exact steps, describe what you were doing as precisely as possible. "I was browsing products, added several to my cart, went to checkout, and the total was wrong" is better than "the cart is broken." The developer may be able to reproduce from an approximate description.

One Bug Per Report

Don't combine multiple issues in one report. "The login fails AND the dashboard loads slowly AND the export button is missing" is three bugs that will be investigated by different people at different times. File three reports. Each gets tracked, prioritized, and resolved independently.

Screenshots and Screen Recordings

A screenshot of the error state is worth a hundred words. A screen recording of the reproduction steps eliminates ambiguity entirely. Tools like Loom (video) or built-in screenshot tools make this easy.

Don't Diagnose — Describe

Your job is to describe the symptom. The developer's job is to diagnose the cause. "The database is corrupted" is a diagnosis (probably wrong). "The user's order history shows orders from a different user" is a symptom (definitely useful).

If you have a theory about the cause, include it in a "Notes" section — but lead with the observable facts.

Severity and Impact

If the bug affects all users, say so. If it affects a specific subset, describe who. If it blocks a critical workflow, state that explicitly. This helps prioritization:

Impact: All users with "+" in their email address cannot log in.
Estimated affected users: ~3% of user base.
Workaround: None — these users are completely locked out.

For Developers: Making Bugs Easy to Report

If your bug reports are consistently vague, the problem might be your reporting process, not your reporters.

Provide a template. An issue template with the five sections pre-filled makes it easy for reporters to include the right information.

Include version numbers in the UI. A "v2.4.1" in the footer means reporters can tell you which version they're using without checking the deployment log.

Add error codes to error pages. "Error 500" is less useful than "Error 500 — REF: abc123." The reference code links to the specific error in your logs.

Key Takeaway

Effective bug reports have five parts: a specific title, numbered reproduction steps, expected behavior, actual behavior, and environment details. One bug per report. Screenshots or recordings when possible. Describe symptoms, not diagnoses. Include severity and impact. The better the report, the faster the fix — a well-written bug report often saves more developer time than it took to write.