How to write a bug report a developer can act on

A good bug report tells a developer exactly how to make the problem happen on their own screen. It needs the steps you took, what you expected, what happened instead, where it happened (device, browser, account, environment) and any evidence such as an error message or screenshot. With those five things, a developer can usually start fixing instead of asking questions.

This guide breaks down each part, shows you how to capture the technical evidence without being technical, gives you a template you can copy and lists the habits that make bugs take longer to fix.

Why does the way you report a bug matter?

Most of the time spent on a bug goes into reproducing it, not fixing it. A message like "checkout is broken" can mean a dozen things: the button doesn't respond, the card is declined, the payment goes through but the order doesn't appear. Each has a different cause in a different part of the code.

If the developer has to guess, they test the wrong thing, ask you questions, wait for answers and lose a day. If they bill by the hour, you pay for that day. A clear report turns a vague complaint into a task.

What should a bug report include?

1. A specific title

Write what goes wrong and where. "Order not created after successful Stripe payment" is useful. "Payments broken!!" isn't.

2. Steps to reproduce

Number them, starting from a state anyone can reach:

1. Log in as a user on the free plan.
2. Go to Settings, then Billing.
3. Click "Upgrade" and pay with a test card.
4. You return to the dashboard.

Then try the steps again yourself. If the bug doesn't happen every time, say how often ("about one in three tries").

3. Expected and actual result

• Expected: the dashboard shows the Pro badge and the new limits.
• Actual: the dashboard still shows the free plan. After refreshing ten minutes later it's still free.

4. Where it happened

The environment (live site, preview, staging), the device, the operating system, the browser and version, and which account you used. "Live site, iPhone, Safari, account test2@yourdomain.com" takes ten seconds to write.

5. When it happened

The date and time, with your time zone. This lets the developer find the exact entry in the server logs.

6. Evidence

A screenshot, a short screen recording or, better still, the technical details described below.

7. Impact

How many users are affected, whether money or data is involved, and whether there's a workaround. This decides priority.

How do you capture the technical details?

Your browser already records the information a developer needs. In Chrome, Edge or Firefox on a computer, the developer tools open with F12 (or Cmd+Option+I on a Mac). Chrome's DevTools documentation explains each panel in detail.

The Console tab

1. Open the developer tools and click Console.
2. Repeat the steps that cause the bug.
3. Look for messages in red. Copy the first red one as text (right-click, copy), or take a screenshot that includes the whole message.

The first error is usually the cause. Later ones are often side effects.

The Network tab

1. Click Network, then repeat the steps.
2. Look for rows in red, or with a status of 400 or higher.
3. Click the row and note its name, its status code and the response text.

A 401 or 403 points at login or permissions, a 404 at a missing route, a 500 at a server error. Our guide on finding what broke in your Lovable or Bolt app explains what these codes usually mean, and monitoring and error tracking shows how to catch them before users report them.

On a phone

Developer tools aren't available on the phone itself, so a screen recording is the next best thing. Both iOS and Android have a built-in screen recorder. Keep it short and start just before the problem.

Is there a template you can copy?

Title: [what goes wrong] on [screen or feature]

Steps to reproduce:
1.
2.
3.

Expected:
Actual:

Environment: live / staging / preview
Device and browser:
Account used:
Date and time (time zone):
How often: every time / sometimes (how often)

Evidence: screenshot, recording, console error, failed request
Impact: who is affected, money or data involved, workaround

What mistakes slow a fix down?

• Several bugs in one message. Report each one separately so each can be tracked, fixed and confirmed.
• Describing the fix instead of the problem. "Make the button blue" hides why. "Users don't notice the button" lets the developer find the right fix.
• Sending passwords. Never share your personal login. Create a test account for the developer instead.
• Only "it doesn't work". Without the steps and what you saw, the developer has to start from nothing.
• Changing things while it's being fixed. If you keep prompting your AI tool in the same area, the bug can move or change shape. Pause until the fix is in.

How do you confirm the fix worked?

When the developer says it's fixed, repeat your original steps on the same environment and device. Then check the area around it: if the bug was in billing, also try cancelling and downgrading. If it comes back, reply in the same thread with what you saw, so the history stays together.

Quick answers

What if I can't reproduce the bug? Report it anyway, with the time, the account and anything you remember. Server logs can often fill in the rest.

Should I use a tool like Jira or GitHub Issues? Any shared place works if it keeps one bug per item. For a small team, GitHub Issues or a shared board is enough.

Do screenshots or recordings work better? Recordings, when the problem involves several steps. Screenshots, when it's one wrong value or one error message.

What about bugs a user reported? Ask the user for the same details, or reproduce it yourself first, before passing it on.

Need someone to act on your bug list?

If you have a list of issues and nobody to fix them, our maintenance and support plans cover ongoing fixes with a person replying within one business day. You can also run the free App Health Check or send us your report.