If your script, bot or dApp backend on Core suddenly throws {"code":-32000,"message":"header not found"}, the node is telling you something very specific: it does not have the block you asked about. This guide explains exactly when Core’s Geth-based RPC returns this error, how it differs from look-alike errors, and how to fix it in a few minutes.
Quick answer
“header not found” means the RPC node you reached has no block header for the block number you passed, almost always because that block is newer than the node’s current head (or does not exist yet). On Core (chain ID 1116), state reads such as eth_call, eth_getBalance and eth_estimateGas with a block number above eth_blockNumber return this error. Fix it by using the latest, safe or finalized tag, clamping your block number to the node’s head, or retrying briefly.
What “header not found” actually means on Core
Core’s node software is a fork of go-ethereum (Geth). In the core-chain source, the function that loads state for a block number first looks up the block header. If no header exists for that number, it returns the plain error header not found. If you passed a block hash instead, the wording becomes header for hash not found. The same logic exists in upstream go-ethereum.
In other words, the node is not saying your contract is broken or your address is wrong. It is saying “I do not know that block.”
What we reproduced on the public Core RPC
On 16 November 2026 we sent read-only JSON-RPC calls to https://rpc.coredao.org, which reported Geth/v1.0.27-90aca9a0-20261031 (matching the core-chain v1.0.27 release) and chain ID 0x45c (1116). Results:
| Request | Block parameter | Response |
|---|---|---|
| eth_getBalance | head + 1, head + 2, head + 5 | -32000 “header not found” |
| eth_call, eth_getCode, eth_getTransactionCount, eth_estimateGas | future block | -32000 “header not found” |
| eth_getBlockByNumber | future block | result: null (no error) |
| eth_getLogs | future range | result: [] (empty, no error) |
| eth_getBalance | unknown block hash | -32000 “header for hash not found” |
| eth_getBalance | block 0x1 (very old) | “missing trie node” (a different error) |
| eth_getBalance | latest, safe, finalized | normal result |
Two takeaways. First, only state methods raise the error; block and log lookups quietly return null or an empty array, which can hide the same bug. Second, an old block does not trigger “header not found” on Core’s public RPC, because the node still has old headers; it just lacks old state. That case is covered in our guide to the “missing trie node” error on Core.
We also checked other public endpoints with the same far-future block: Ankr (rpc.ankr.com/core) and Core’s archive RPC (rpcar.coredao.org) returned “header not found”, while dRPC (core.drpc.org) returned unsupported block number. Same cause, different wording.
Common causes
1. Your block number came from a different node
This is the classic cause. You read the newest block number from one source (a WebSocket subscription, another provider, or a different backend behind a load balancer) and then query a node that is a block or two behind. For a moment, that node has never heard of the block, so it answers “header not found”. With Core producing a block roughly every 3 seconds, the window is short but real for bots that react instantly to new blocks.
2. Off-by-one or arithmetic errors
Code like head + 1, a loop that runs one step too far, or a “toBlock” calculated from a timestamp can point past the chain head.
3. Wrong chain or wrong network
A block number saved from a different chain (for example a testnet, or another EVM network) may simply not exist yet on Core mainnet.
4. A block hash the node does not know
Passing a hash from a reorged-out block, a different chain or a typo produces “header for hash not found”. If you use the EIP-1898 object form with requireCanonical: true, a known but non-canonical hash returns “hash is not currently canonical” instead, according to the core-chain source.
5. A node that is still syncing
If you run your own Core node, check eth_syncing. A syncing node is behind the network, so recent block numbers do not exist on it yet. The public RPC returned false (fully synced) in our test.
How to fix “header not found”: step by step
Step 1: Confirm you are on Core and compare with the node’s head
Ask the same endpoint you are querying for its chain ID and latest block:
curl -s -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}' \
https://rpc.coredao.org
curl -s -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' \
https://rpc.coredao.org
The chain ID should be 0x45c. If the block number in your failing request is higher than the eth_blockNumber result, you have found the problem. You can also look the block number up on Core Scan to see whether it exists yet.
Step 2: Use a block tag when you just want current data
If you need “now”, let the node resolve the block itself. The standard JSON-RPC spec defines latest, safe, finalized and pending tags. A tag can never point past the node’s own head.
{"jsonrpc":"2.0","id":1,"method":"eth_getBalance",
"params":["0xYourAddress","finalized"]}
In our test, the finalized block was 3 blocks behind latest. If you want to know why that gap exists, see our explainer on Core transaction finality.
Step 3: Clamp numeric blocks to the node’s head
When you must use a specific number (indexers, backfills), ask the same provider for its head and never go past it:
import { JsonRpcProvider } from "ethers"; // ethers v6
const provider = new JsonRpcProvider("https://rpc.coredao.org", 1116);
async function safeBlock(wanted) {
const head = await provider.getBlockNumber();
return Math.min(wanted, head);
}
const block = await safeBlock(targetBlock);
const balance = await provider.getBalance("0xYourAddress", block);
Step 4: Retry briefly on this specific error
If your block number comes from a subscription or another provider, a short retry usually resolves it once the node catches up. Only retry on “header not found”; other errors need a different fix.
async function withHeaderRetry(fn, tries = 5, delayMs = 1000) {
for (let i = 0; i < tries; i++) {
try {
return await fn();
} catch (err) {
const msg = JSON.stringify(err?.error ?? err?.info ?? err?.message ?? "");
if (!msg.includes("header not found") || i === tries - 1) throw err;
await new Promise(r => setTimeout(r, delayMs));
}
}
}
const bal = await withHeaderRetry(() => provider.getBalance(addr, blockNumber));
Step 5: Stick to one endpoint per request flow
Do not read the head from provider A and query provider B. If you use a fallback setup, fetch the head and do the follow-up reads on the same endpoint, or pass a tag instead of a number.
Step 6: Treat null and empty results with care
Because eth_getBlockByNumber returns null and eth_getLogs returns [] for future blocks, an indexer can silently skip data. Always cap toBlock at the head, and split large ranges as described in our eth_getLogs “block range is too large” guide.
“header not found” vs similar errors
- header not found: no header for that block number on this node (usually a future block).
- header for hash not found: the node does not know that block hash.
- missing trie node: the node has the block but not its old state; use an archive RPC.
- unsupported block number: dRPC’s wording for a block it cannot serve, which in our test was a future block.
- invalid argument 1: hex string without 0x prefix: you passed a decimal string like
"123"; block numbers must be hex strings such as"0x7b". Leading zeros ("0x0FF") are also rejected.
FAQ
Is my transaction or my funds affected?
No. “header not found” comes from read calls and concerns which block you asked about. It does not move funds or change anything on-chain.
Do I need an archive node to fix it?
Usually not. On Core’s public RPC, old blocks produced “missing trie node”, not “header not found”. An archive node only helps with old state, not with blocks that do not exist yet.
Why does it happen only sometimes?
Intermittent errors almost always mean a race: your block number is from a slightly faster source than the node you query. Retrying after a second or using a block tag fixes it.
Can MetaMask show this error?
Wallets read through an RPC endpoint too, so a lagging or misconfigured custom RPC can surface it. Check that your network settings match the official values in our add Core to MetaMask guide and the Core network config docs.
Disclaimer: This article is for educational purposes only and is not financial or investment advice. RPC behaviour and error wording can change with node upgrades; test against your own endpoint.
