nautechsystems/nautilus_trader · error

eth_getBlockByNumber returned no result for block tag {tag}

Error message

eth_getBlockByNumber returned no result for block tag {tag}

What it means

`block_by_tag` executes `eth_getBlockByNumber` and expects a block object back; when the node responds with `null` (JSON-RPC `result: null`), the library converts that to this error. Per the eth_getBlockByNumber spec, null means no block exists for the tag, so the library refuses to fabricate an empty block.

Source

Thrown at crates/adapters/blockchain/src/rpc/http.rs:691

            .block_by_tag(&format!("0x{number:x}"), full_transactions)
            .await?;
        anyhow::ensure!(
            block.number == number,
            "eth_getBlockByNumber returned block {} for requested block {number}",
            block.number
        );
        Ok(block)
    }

    async fn block_by_tag(&self, tag: &str, full_transactions: bool) -> anyhow::Result<RpcBlock> {
        let result: Option<RpcBlockResponse> = self
            .execute_execution_rpc_call(
                "eth_getBlockByNumber",
                serde_json::json!([tag, full_transactions]),
            )
            .await?;
        let response = result.ok_or_else(|| {
            anyhow::anyhow!("eth_getBlockByNumber returned no result for block tag {tag}")
        })?;
        let mut block = response.block;
        if full_transactions {
            block.transactions = response
                .transactions
                .into_iter()
                .map(|transaction| {
                    serde_json::from_value(transaction).map_err(|_| {
                        anyhow::anyhow!(
                            "Failed to parse full transaction in eth_getBlockByNumber response"
                        )
                    })
                })
                .collect::<anyhow::Result<_>>()?;
        }
        Ok(block)
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Check the requested tag/height exists: compare against `eth_blockNumber` (head) and node history depth
2. For old heights use an archive node; pruned full nodes return null for pruned bodies/heights
3. For `finalized`, confirm the execution node has a connected consensus client and a finalized head
4. Retry if a reorg may have transiently orphaned the height

Example fix

// before: pruned node asked for a deep historical block -> null
let block = client.block_by_tag("0x3a2f1", false).await?; // Err: returned no result
// after: use an archive endpoint for historical heights
let block = if height < SAFE_DEPTH { archive_client.block_by_tag(tag, false).await? } else { full_client.block_by_tag(tag, false).await? };

async fn block_exists(url: &str, tag: &str) -> bool {
    send_raw(url, json!({"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":[tag,false],"id":1}))
        .await.ok()
        .map(|v| !v["result"].is_null())
        .unwrap_or(false)
}

match client.block_by_tag(tag, full).await {
    Ok(b) => Ok(b),
    Err(e) if e.to_string().contains("returned no result") => {
        Err(anyhow!("block {tag} unavailable on this node (pruned or not yet mined); use an archive node"))
    }
    Err(e) => Err(e),
}

When it happens

Trigger: Requesting a block tag that the node has no block for: a height in the future or below the pruned horizon with no archive data, the `finalized` tag when no finalized head exists yet, or a reorg orphaning the requested height.

Common situations: Freshly synced node without archive history queried for old heights; `finalized` tag on a node lacking a consensus client; querying a pending/future block number; provider tiers without archive access.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• eth_getBlockByNumber returned block {} for requested block {
• Included wrap transaction {tx_hash} has invalid block number
• RPC error {}: {}
• {method} RPC error {code}
• {method} RPC error {}

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/ef337e6318a44b70. Report an issue: GitHub.