{"record":{"id":"bc29ea27f758bbea","repo":"nautechsystems/nautilus_trader","slug":"canonical-head-head-block-is-behind-execution-cr","errorCode":null,"errorMessage":"Canonical head {head_block} is behind execution creation block {from_block}","messagePattern":"Canonical head (.+?) is behind execution creation block (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":3574,"sourceCode":"                effective_gas_price: &effective_gas_price,\n                manifest_version: &self.manifest_version,\n                manifest_digest: &self.manifest_digest,\n                provider_ids: &self.provider_ids,\n                operator_ids: &self.operator_ids,\n                failure_domain_ids: &self.failure_domain_ids,\n                decisions: &decisions,\n                finalized_headers: &included.finality.finalized_headers,\n            })\n            .await\n    }\n\n    fn release_slot(&self) {\n        *self.in_flight.lock() = None;\n    }\n}\n\nfn replacement_scan_range(from_block: u64, head_block: u64) -> anyhow::Result<RangeInclusive<u64>> {\n    anyhow::ensure!(\n        head_block >= from_block,\n        \"Canonical head {head_block} is behind execution creation block {from_block}\"\n    );\n    let max_end = from_block.saturating_add(MAX_REPLACEMENT_SCAN_BLOCKS - 1);\n    Ok(from_block..=head_block.min(max_end))\n}\n\nfn current_unix_secs() -> anyhow::Result<u64> {\n    SystemTime::now()\n        .duration_since(UNIX_EPOCH)\n        .map_err(|_| anyhow::anyhow!(\"Trusted host clock precedes the Unix epoch\"))\n        .map(|duration| duration.as_secs())\n}\n\nfn validate_payload_operation_batch_size(batch_size: usize) -> anyhow::Result<i64> {\n    anyhow::ensure!(\n        (1..=MAX_PAYLOAD_OPERATION_BATCH_SIZE).contains(&batch_size),\n        \"Payload operation batch size must be between 1 and {MAX_PAYLOAD_OPERATION_BATCH_SIZE}\"","sourceCodeStart":3556,"sourceCodeEnd":3592,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L3556-L3592","documentation":"`replacement_scan_range` computes the block range to scan for a replacement transaction and requires the current canonical head to be at or beyond the original creation block. A head behind `from_block` means the chain view regressed relative to the execution's own history (fork/reorg or connected to a stale/different node), so no valid scan range exists.","triggerScenarios":"Requesting a replacement (speed-up/cancel) scan when `head_block < from_block` — e.g. after switching to a lagging RPC node, or a reorg that rolled the head below the block where the original transaction was created.","commonSituations":"Failover to an unsynced RPC endpoint; connecting to a different network with lower block height; misconfigured `from_block` computed from a wrong clock or chain data.","solutions":["Check the connected node's sync status and chain ID; wait for it to reach at least `from_block`.","Re-point the client at the previously used healthy RPC endpoint.","Recompute `from_block` from current canonical chain data."],"exampleFix":"// before: failover to lagging node\nlet head = lagging_provider.block_number().await?; // 800\nreplacement_scan_range(1000, head)?; // ensure! fails\n// after: guard before scanning\nensure!(head >= from_block, \"waiting for node sync\");","handlingStrategy":"validation","validationCode":"let head = provider.block_number().await?;\nanyhow::ensure!(head >= from_block, \"node head {} behind creation block {}\", head, from_block);","typeGuard":null,"tryCatchPattern":"match replacement_scan_range(from_block, head) {\n    Err(e) if e.to_string().contains(\"behind execution creation block\") => wait_for_sync_then_retry().await,\n    other => other,\n}","preventionTips":["Check node sync state after any RPC failover","Verify chain ID matches the previous endpoint","Compute from_block from canonical chain data, not local clocks"],"tags":["blockchain","reorg","rpc","range"],"backgroundTag":"invalid-argument-value","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}