Rendered Fewer Hooks Than Expected: React's Singly Linked List

Ever hit this error and wondered what actually broke?

⚠️ The error

"Rendered fewer hooks than expected. This may be caused by an accidental early return statement."

The root cause is simpler than it looks — and it comes down to how React tracks Hooks internally.

How React tracks Hooks

React doesn't know your variable names. It associates each Hook with a component purely by call order:

• Every Fiber keeps a singly linked list of Hook state entries — one node per useState, useEffect, useRef, and other Hook call.
• Nodes sit in the exact order you wrote the calls in.
• On every render, React walks that list from the head, matching list position $N$ to whichever Hook call comes $N$th in your function.
• No names, no keys involved — just position.

What actually breaks it

The number and order of Hook calls has to stay identical between renders of the same component implementation. You can reorder Hooks between code versions — ship a new build, and the list just gets rebuilt from scratch. What breaks things is a mismatch within a single render cycle: a condition, a loop, or an early return that causes render $N$ to call a different number of Hooks than render $N - 1$.

React then tries to walk the linked list against a function that no longer produces the same sequence, loses track of which node belongs to which call, and throws.

The rule

This is the real reason Hooks must be called at the top level. It isn't a style preference — it's a structural requirement of a linked list that has no way to reconcile itself against a shape it wasn't built for.

Have you run into this one in a real codebase?