React Errors Debugging

react-errors-debugging

Quick Reference

Debugging Tools Overview

Critical Warnings

NEVER remove <StrictMode> to "fix" double-rendering issues -- the double invocation is intentional. It exposes impure components and side effects. ALWAYS fix the underlying impurity instead.

NEVER ignore React console warnings -- they indicate real bugs or future breaking changes. ALWAYS resolve every warning before shipping.

NEVER debug production builds without source maps -- error messages are stripped and minified in production. ALWAYS generate source maps for staging/debugging environments.

ALWAYS check the component stack trace when diagnosing errors -- React prints the component tree path that led to the error, which pinpoints the source.

ALWAYS use the Profiler tab (not just the Components tab) when investigating performance -- visual inspection of the component tree does NOT reveal render timing.

Strict Mode

<StrictMode> is a development-only tool that helps find bugs by intentionally double-invoking certain functions.

What Strict Mode Double-Invokes

Strict Mode Behavior

// StrictMode wraps your app (or a subtree)
import { StrictMode } from "react";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

In development, React will:

1. Render component -> call cleanup -> re-render component (simulating unmount/remount)
2. Call state initializers twice and discard the first result
3. Call reducers twice and discard the first result

Common Strict Mode Mistakes

// BAD: Side effect in render — Strict Mode exposes this by double-calling
function Counter(): JSX.Element {
  const [count, setCount] = useState(0);
  document.title = `Count: ${count}`; // NEVER do this in render
  return <div>{count}</div>;
}

// GOOD: Side effect in useEffect
function Counter(): JSX.Element {
  const [count, setCount] = useState(0);
  useEffect(() => {
    document.title = `Count: ${count}`;
  }, [count]);
  return <div>{count}</div>;
}

// BAD: Effect without cleanup — Strict Mode exposes the leak
function ChatRoom({ roomId }: { roomId: string }): JSX.Element {
  useEffect(() => {
    const connection = createConnection(roomId);
    connection.connect();
    // Missing cleanup! StrictMode will connect TWICE
  }, [roomId]);
  return <div>Chat: {roomId}</div>;
}

// GOOD: Effect with proper cleanup
function ChatRoom({ roomId }: { roomId: string }): JSX.Element {
  useEffect(() => {
    const connection = createConnection(roomId);
    connection.connect();
    return () => connection.disconnect(); // ALWAYS clean up
  }, [roomId]);
  return <div>Chat: {roomId}</div>;
}

Console Warnings Diagnostic Table

React DevTools

Components Tab

The Components tab shows the live component tree with inspectable data:

Profiler Tab

Profiler Workflow

1. Open React DevTools -> Profiler tab
2. Click gear icon -> enable "Record why each component rendered while profiling"
3. Click Record (blue circle)
4. Perform the interaction you want to measure
5. Click Stop
6. Analyze: flamegraph for overview, ranked chart for worst offenders
7. Check "Why did this render?" for each slow component

Component Stack Traces

When React throws an error, it prints a component stack trace showing the component hierarchy:

Error: Something went wrong
    at UserProfile (UserProfile.tsx:15)
    at div
    at Dashboard (Dashboard.tsx:8)
    at ErrorBoundary (ErrorBoundary.tsx:5)
    at App (App.tsx:12)

Reading Component Stacks

• Read top to bottom: the topmost component is where the error occurred
• Native HTML elements (e.g., at div) appear in the stack
• File names and line numbers point to the component definition
• ALWAYS look at the first custom component in the stack -- that is the error source

React 19 Improvements

React 19 introduces owner stacks via captureOwnerStack():

import { captureOwnerStack } from "react";

// In an error boundary or error handler:
function handleError(error: Error): void {
  const ownerStack = captureOwnerStack();
  console.error("Error:", error.message);
  console.error("Owner stack:", ownerStack);
  // Owner stack shows WHICH component created the erroring component
  // (not just the render tree, but the ownership/creation chain)
}

Common Error Messages Diagnostic Table

Development vs Production Differences

Debugging Production Errors

1. Look up minified error codes: Visit https://react.dev/errors/{code} for the full message
2. Generate source maps: Configure your bundler to produce .map files for staging
3. Use profiling build for production performance analysis:

// webpack.config.ts — alias for profiling build
resolve: {
  alias: {
    "react-dom$": "react-dom/profiling",
    "scheduler/tracing": "scheduler/tracing-profiling",
  },
}

4. Error monitoring: Use services that can decode source maps server-side (Sentry, Bugsnag)

React 19 Debugging Improvements

Debugging Tools Setup

React DevTools Extension

ALWAYS install the React DevTools browser extension for Chrome or Firefox. It adds the Components and Profiler tabs to browser DevTools.

• Chrome: Search "React Developer Tools" in Chrome Web Store
• Firefox: Search "React Developer Tools" in Firefox Add-ons
• Standalone (for React Native/iframe): npx react-devtools

why-did-you-render Library

For granular re-render tracking beyond DevTools Profiler:

// wdyr.ts — MUST be imported BEFORE React
import React from "react";

if (process.env.NODE_ENV === "development") {
  const whyDidYouRender = await import("@welldone-software/why-did-you-render");
  whyDidYouRender.default(React, {
    trackAllPureComponents: true,
  });
}

// Then on specific components:
MyComponent.whyDidYouRender = true;

Reference Links

• references/examples.md -- Debugging workflow examples with step-by-step instructions
• references/anti-patterns.md -- Common debugging mistakes and how to avoid them

Official Sources

• https://react.dev/learn/react-developer-tools
• https://react.dev/reference/react/StrictMode
• https://react.dev/reference/react/Profiler
• https://react.dev/errors
• https://react.dev/blog/2024/04/25/react-19