Learning center

Turn a browser symptom into a bug report another engineer can act on

A useful browser bug report names the symptom, two causes that could explain it, and the one observation that tells them apart. This guide shows how to find that observation with DevTools and write it down.

Why "it's broken" stalls#

The person who saw a failure knows more than they write down. They saw the order of events, the page they started from and the moment it went wrong. The engineer who receives the report sees one sentence and a screenshot. A screenshot shows the final state of the page. It does not show which request ran, what it returned or which script threw.

Most browser symptoms have more than one plausible cause, and the causes live in different code. A spinner that never stops can mean the server never answered, or that it answered and the page failed to render the answer. The first is a backend or network problem. The second is a frontend bug. Until the report says which, the receiver has to reproduce the whole failure before they can even pick the right repository.

A report becomes useful when it does that sorting for them. You do not need to know the root cause. You need to record the observation that rules one family of causes out.

The method: symptom, two causes, one deciding observation#

  1. Write the symptom as observed. "After clicking Save, the button stays disabled and the spinner never stops" is a symptom. "The API is down" is a hypothesis.
  2. Name two plausible causes. Pick causes that would need different fixes or different owners. If you can only think of one, the report is a guess; ask what else would produce the same screen.
  3. Find the observation that separates them. It is usually a single fact in the Network panel, the Console or the DOM: did the request leave the browser, what status came back, did a script throw after the response arrived.
  4. Reproduce once with recording on. Open DevTools before the failing step, turn on Preserve log in the Network panel so a navigation does not clear the list, and repeat the steps. Network panel reference
  5. Write the report around the deciding observation. Put it first, with the exact text, timestamp and request. Then add steps, environment and what you could not establish.

The rest of this collection applies the same method to specific symptoms. Each guide names the two causes that are most often confused and the observation that separates them.

Worked example: a spinner that never stops#

This example is fictional and reproducible with any app that loads data after a click. An engineer reports that the order history page shows a spinner forever after they press Load older orders.

Cause A: the response never arrivedCause B: the response arrived and rendering failed
Network panelThe request to /api/orders?before=… stays pending, or ends with (failed)The request ends with 200 and a JSON body
ConsoleNothing new, or Failed to load resourceAn uncaught exception such as TypeError: Cannot read properties of undefined (reading 'map')
OwnerServer, proxy or networkFrontend code that handles the response

The deciding observation is the row for that request in the Network panel. In this case it showed 200, and its Response tab held {"orders": null, "next": null}. The Console showed the TypeError at the same second. That rules out Cause A, and the report can open with one sentence: the server returned orders: null for the last page, and the page's rendering code threw on it.

That sentence changes what the receiver does. They do not need to check server health. They need to decide whether null is a valid answer for an empty page, which is a contract question between the API and the client, and fix whichever side is wrong.

What the report should contain#

Use the fields from a standard template and add the deciding observation at the top. A copyable browser bug report template lists the fields; this collection is about what goes in them.

FieldWriteAvoid
Deciding observationThe exact request, status, console text or DOM fact, with its timeA conclusion with no observation behind it
SymptomWhat you saw, in the words the UI used"Broken", "doesn't work"
StepsThe starting page and state, then each actionSteps that start after the failure
EnvironmentBrowser and version, account role, build or release if the page shows oneYour whole machine specification
Ruled outWhat you checked and what it showedSilence about checks you made
UnknownWhat you could not observe, such as the server logGuessing to fill the gap

Copy error text instead of retyping it, and keep the request URL, method and status together. If a value in a URL, header or body identifies a person or a session, replace it with a placeholder and say you did. The HAR guide covers what a network export carries.

Choose the guide for your symptom#

Limits of browser evidence#

Browser evidence shows what one browser sent, received and ran. It does not show why the server answered the way it did, which deploy served the response, or whether other users see the same thing. Say so in the report and name the log or record that would answer it, such as the server's access log for the request ID in a response header.

A reproduction also differs from the original session. Caches warm up, cookies change and a deploy can land between attempts. Record the time of each attempt so the receiver can line it up with server logs and releases.

Record the timeline with Session Recorder#

Session Recorder, a free Chrome extension from Proofline, records clicks, console errors, network activity and screenshots on one timeline while you reproduce a failure, then exports a Markdown report. Recording and export need no account. The setup guide covers installation and export. Review the export before you share it, because automatic redaction can miss values.

Questions#

What if I cannot think of a second cause?

Ask what else would produce the same screen. Most symptoms have a client-side and a server-side explanation, or a "never happened" and a "happened but was ignored" explanation. If you still have one cause, write it as a hypothesis and list the observation that would confirm it.

Should I attach a video?

A video shows the order of visible events and is useful for layout or animation problems. It does not show requests, responses or console errors, so attach it alongside the deciding observation, not instead of it.

How much of the network log should I include?

Include the requests around the failure and the one that decides the cause. A full export is useful when the receiver needs timing or ordering, but it also carries cookies, tokens and personal data unless you remove them first.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading