debug-frontend-browser

name	debug-frontend-browser
description	Diagnoses runtime UI bugs live in the browser — console/network errors, hydration mismatches, failed renders, CORS, broken interactions; used when a page misbehaves at runtime.
when_to_use	When the UI misbehaves at runtime — blank screen, hydration mismatch error, console/network errors, CORS failures, broken click/interaction, or 'works in dev not prod' — and needs live browser inspection.

When to Use

The page is already rendering (or failing to) in a real browser and behaves wrong. Reach here when:

• Blank/white screen, partial render, or content flashes then disappears.
• Console error: Hydration failed, Text content does not match server-rendered HTML, Cannot read properties of undefined, etc.
• Network tab shows 4xx/5xx, a request stuck pending, or a CORS rejection.
• A click/submit/keypress does nothing or fires the wrong handler.
• "Works in dev, breaks in prod" (minified build, different env, SSR vs CSR mismatch).

Not for: build/compile failures (no browser yet), pure logic bugs reproducible in a unit test, or backend-only errors. Route those to general root-cause debugging. This skill is browser-runtime UI only and uses the chrome-devtools MCP to inspect a live page.

Steps

1. Get a live page. list_pages to see open tabs; select_page the offending one, or new_page + navigate_page to the failing URL. Reproduce the exact state the bug needs (route, query params, logged-in session). If repro needs interaction, drive it: click / fill / press_key. Note: a fresh new_page has no auth cookies — reuse the existing tab when the bug is session-dependent.

2. Drain the console first. list_console_messages — read every error and warning, not just the top one. The first error is usually the root; later ones are fallout. Capture the full stack trace via get_console_message for the key error. Map minified frames back to source using the file:line in the trace (sourcemaps); if prod sourcemaps are absent, re-run the same flow against the dev/staging build to get readable frames.

3. Check failed network requests. list_network_requests, then get_network_request on anything non-2xx, pending, or that the failing component depends on. Inspect: status code, response body (real error message often lives here, not the console), request/response headers. For CORS: confirm the server returned Access-Control-Allow-Origin matching the page origin and, for preflight, that the OPTIONS request succeeded with the right Access-Control-Allow-Methods/Headers. CORS is a server-config fix — never "fix" it by disabling browser security or proxying around it silently.

4. Hydration mismatch (Next.js / React). The cause is server HTML ≠ first client render. Hunt for non-deterministic-in-render values: Date.now() / new Date() / Math.random(), window/localStorage/navigator read during render, typeof window !== 'undefined' branches, locale/timezone-dependent formatting, and invalid DOM nesting (<div> inside <p>, <p> inside <p>). Take take_snapshot to see the actual client DOM and compare against the SSR HTML (view the document response in get_network_request). Fix at source: gate client-only values behind useEffect/mounted-flag or next/dynamic({ ssr: false }). Use suppressHydrationWarning only for genuinely unavoidable per-render values (e.g. a timestamp) — it silences the warning, it does not fix a real divergence.

5. Layout / styling bug. take_screenshot for the visual, take_snapshot for the structured DOM + roles. evaluate_script to read computed styles on the culprit node (getComputedStyle(el)), bounding box, overflow, z-index, and whether the element is actually in the DOM vs display:none/zero-size. Distinguish "not rendered" (missing from snapshot) from "rendered but invisible" (present, hidden by CSS).

6. Broken interaction / event wiring. Confirm the handler is attached and the right element receives the event. evaluate_script to inspect listeners, check for an overlay intercepting clicks (document.elementFromPoint(x,y)), pointer-events:none, disabled state, or a stale closure capturing old state. Reproduce the click with click and re-read the console/network to see what (if anything) fired. For React state bugs, log or read the value at the moment of interaction rather than assuming.

7. Confirm root cause, fix at source. Tie the symptom to one concrete cause (a specific request, a specific render expression, a specific listener). Fix the source code — do not swallow the error with an empty catch, a blanket try/catch, or by hiding the failing UI.

8. Verify live. Reload via navigate_page (or reload), re-run the repro interaction, then re-check: list_console_messages clean of the original error, list_network_requests shows the request now 2xx, take_screenshot shows correct render. Show the before/after as evidence — do not declare fixed on code-read alone.

Common Errors

• Reading only the first console line. The headline error is often downstream; scroll the full list and trace the earliest one.
• Trusting the console over the network body. A 500 shows a generic message in console but the real stack/error is in the response body — always get_network_request it.
• "Fixing" CORS client-side. Adding mode: 'no-cors', disabling web security, or routing through a hack hides it. CORS is fixed on the server's response headers (or preflight) only.
• Blaming hydration on the wrong line. React points at the mismatched node, but the cause is why server and client disagree there — usually a non-deterministic value or a window read, not the JSX at that line.
• suppressHydrationWarning as a cure. It mutes the symptom. If the underlying data genuinely differs, you've shipped a silent inconsistency. Use it only for inherently dynamic content, never to paper over a real bug.
• Fresh tab missing auth. new_page starts with no session — a bug that needs login won't reproduce. Reuse the existing authenticated tab.
• Minified prod stack with no sourcemap. Frames like a.b is not a function are useless; reproduce against dev/staging to get real file:line.
• Stale page state. Inspecting after the error already cleared (e.g. an error boundary swapped the UI) shows the recovered state. Re-trigger the failure, then inspect immediately.
• Race / timing. Element or data not there yet — use wait_for on the target before asserting it's missing, instead of concluding it never renders.

Verify

Fix is done only when all hold against the live page:

• Original console error/warning gone from list_console_messages after reload + repro.
• Previously-failed request now returns 2xx with a valid body (check get_network_request).
• take_screenshot shows the page rendering correctly through the exact repro steps.
• The broken interaction now fires the correct handler and produces the expected result.
• No new errors introduced, and the error is fixed at source — not suppressed, caught-and-ignored, or hidden.
• If it was a "dev-only / prod-only" bug, verified in the build that originally failed.