RPC error -32000: header not found

Last updated: September 16, 2026

At a glance

Cause

Upstream nodes return -32000 'header not found' when the requested block header is absent: it is beyond the node's retained history, or the node has not yet caught up to it. Our outcome classifier treats it as a history boundary rather than a node failure, and the Robinhood router retries the read once against a different host before answering. Branch on code AND message: on BNB Smart Chain -32000 is ambiguous — 'header not found' means the block is missing, while pruned or unsupported-state wording means historical state is unavailable on the selected node.

Solution

1. Check the block exists at the head you expect: a number above the current head arrives before the node syncs it, and a short wait resolves it.
2. For deep history, do not assume archive depth — read the measured boundary on the network's own page instead of retrying blindly.
3. On BSC, branch on the pair code + message: 'header not found' is a missing block, pruned or unsupported-state wording is missing state, and the two need different fallbacks.
4. Do not treat it as an empty result: an absent header says the node cannot answer, not that the block has no content.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "header not found"
  }
}