Chapter 45: React Compiler — Debugging and Troubleshooting

Core Idea

Most compiler-adoption bugs turn out to be pre-existing Rules-of-React violations that manual memoization happened to mask — the debugging workflow is about finding and fixing that root cause, not about disabling the compiler.

Key Concepts

Understanding compiler behavior first: the compiler only memoizes code it can prove is safe under the Rules of React — if it can't prove safety for a piece of code, it leaves that code un-optimized rather than guessing, so a correctness bug it "causes" is almost always actually a bug it exposes.
Common breaking patterns: mutating a value that's supposed to be treated as immutable (props, state, memoized values), relying on a component/Hook re-running on every render for a side effect that isn't expressed as a real dependency, and other Rules-of-React violations that used to "work" only because nothing was memoized before.
Debugging workflow: isolate the affected component, check whether disabling compilation for just that function (via a "use no memo" directive) makes the symptom disappear — if it does, the bug is a Rules-of-React violation in that function, not a compiler defect; fix the violation rather than leaving the directive in permanently.
Reporting compiler bugs: when a component follows the Rules of React correctly but the compiler still produces incorrect behavior, that's a genuine compiler bug worth reporting upstream — distinct from the far more common "my code broke the rule the compiler exposed" case.

Code Examples

function Suspect() {
  "use no memo"; // isolate: does disabling compilation here fix the bug?
  // ...
}

What it demonstrates: the diagnostic technique — a targeted opt-out to confirm whether a bug is compiler-caused or a pre-existing Rules-of-React violation the compiler surfaced.

Key Takeaways

Treat a bug that appears after enabling the compiler as "find the Rules-of-React violation" first, not "the compiler is broken."
"use no memo" is a diagnostic and escape-hatch tool, not a long-term fix — use it to isolate, then repair the underlying code.
Only report a compiler bug once you've confirmed the affected code genuinely follows the Rules of React and the compiler still misbehaves.

Connects To

Ch 44 (Incremental Adoption): where this troubleshooting workflow gets applied during rollout.
Ch 114 (Components and Hooks Must Be Pure): the most common root cause of compiler-adoption bugs.
Ch 92 (React Compiler — Configuration & Directives Reference): the full reference for the "use no memo" directive.