What is a blockchain reorg, and how do indexers handle it?

Updated August 2026

A chain reorganisation — a reorg — happens when a blockchain replaces recently accepted blocks with an alternative chain that has more accumulated work or stake. Transactions in the discarded blocks may never have happened as far as the canonical chain is concerned.

For an indexer this is the hardest correctness problem in the job, because the failure is silent. Nothing errors. You simply hold records derived from blocks that no longer exist.

Why do reorgs happen?

Because block production is distributed. Two validators can produce valid blocks at nearly the same height, and the network briefly disagrees about which is canonical. When it converges, one branch is discarded along with everything in it.

Depth varies by chain and by conditions. Most reorgs are one or two blocks. Deeper ones are rarer and more damaging, precisely because a naive indexer has had longer to act on the bad data.

What goes wrong if you ignore them?

Your derived data quietly diverges from the chain.

A swap you recorded did not happen. A balance you computed is wrong. A notification fired for a transaction that no longer exists. None of this raises an error — the records are perfectly well-formed, they just describe a version of history the chain has abandoned.

These bugs surface weeks later as totals that do not reconcile, and they are extremely difficult to trace back to their cause.

How do indexers handle it?

Strategy	How it works	Trade-off
Ignore	Treat every block as final	Fast, and wrong
Confirmation depth	Wait N blocks before processing	Simple, adds latency, still fails on deep reorgs
Cursors	Track exact stream position including fork context	Correct, requires the source to support it

Confirmation depth is the common compromise — wait twelve blocks, or thirty-two, and treat anything older as settled. It works most of the time and costs you latency proportional to the safety margin. It also has no answer for a reorg deeper than your threshold.

Cursor-based handling is what Firehose does. Every block carries a cursor identifying its exact position, including fork context. When a reorg happens, the stream explicitly signals which blocks were undone rather than quietly moving on, so a consumer can reverse the derived data. A consumer that disconnects reconnects with its last cursor and resumes at precisely the right point.

That distinction — being told what was undone rather than having to detect it — is what makes correctness achievable without paying a latency penalty for it.

What should I do in my own pipeline?

Store block number and hash with every derived record. Without these you cannot work out what to undo.

Make your writes reversible. Append-only stores need a strategy — a version column with row replacement, or delaying writes past a confirmation depth.

Handle the undo signal. If your source tells you blocks were reverted, act on it rather than logging and continuing.

Test it. Reorgs are rare enough that untested handling code is usually broken handling code.

Frequently asked questions

How deep can a reorg go? Usually one or two blocks. Deeper reorgs are rare but do happen, and depth varies by chain and consensus mechanism.

Do reorgs affect historical data? No. Blocks deep in history are settled. The risk is confined to recent blocks near the chain head.

Is confirmation depth good enough? Often, if you can accept the latency and the residual risk of a deeper reorg. Cursor-based handling gives correctness without the latency trade.

Get an API key at thegraph.market — no personal information required.