{"record":{"id":"afabb79d18aad75f","repo":"nautechsystems/nautilus_trader","slug":"replacement-block-conflicts-with-its-canonical-hea","errorCode":null,"errorMessage":"Replacement block conflicts with its canonical header","messagePattern":"Replacement block conflicts with its canonical header","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":3087,"sourceCode":"                \"canonical replacement window\",\n            )?;\n            decisions.push(verification_decision(&window, Some(start), Some(end)));\n            blocks = window.value;\n        } else {\n            let start_header = required_verification(\n                self.verification.verify_block(start).await,\n                \"canonical replacement start header\",\n            )?;\n            decisions.push(verification_decision(\n                &start_header,\n                Some(start),\n                Some(start),\n            ));\n            let start_block = required_verification(\n                self.verification.verify_replacement_block(start).await,\n                \"canonical replacement start block\",\n            )?;\n            anyhow::ensure!(\n                VerifiedBlockHeader::from(start_block.value.clone()) == start_header.value,\n                \"Replacement block conflicts with its canonical header\"\n            );\n            decisions.push(verification_decision(\n                &start_block,\n                Some(start),\n                Some(start),\n            ));\n            blocks.push(start_block.value);\n\n            if end > start {\n                let window = required_verification(\n                    self.verification\n                        .verify_replacement_window(start_header.value, end)\n                        .await,\n                    \"canonical replacement window\",\n                )?;\n                decisions.push(verification_decision(&window, Some(start + 1), Some(end)));","sourceCodeStart":3069,"sourceCodeEnd":3105,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L3069-L3105","documentation":"When starting a replacement scan from scratch, the client fetches the canonical header at the start block and, independently, the replacement (full) block at that height, then requires the block's derived header to match the canonical header. A mismatch means the two RPC views of the same block height disagree — typically a reorg or an inconsistent node.","triggerScenarios":"verify_replacement_block(start) returned a block whose header hash/fields differ from verify_block(start) for the same height, usually because the RPC served the block from different branches of a reorg, or a misconfigured node served a different chain.","commonSituations":"Live chain reorg at the start height; load-balanced RPC routing requests to different nodes mid-reorg; provider serving cached data from before the reorg; accidentally switching between mainnet and a fork/testnet endpoint.","solutions":["Retry the scan after the reorg settles; the two views should converge","Pin all requests to a single trusted RPC node instead of a load balancer","Confirm both endpoints resolve to the same chain_id","Clear or advance the replacement cursor and re-run reconciliation"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"let header = client.block_header(start).await?;\nlet block = client.replacement_block(start).await?;\nif VerifiedBlockHeader::from(block) != header {\n    return Err(\"provider views disagree; wait for reorg to settle\");\n}","typeGuard":null,"tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"conflicts with its canonical header\") => {\n        tokio::time::sleep(reorg_settle_delay).await;\n        retry_scan()\n    }\n    other => other,\n}","preventionTips":["Pin to a single RPC endpoint instead of a load balancer","Wait for a few confirmations before scanning near the head","Compare chain_id across providers","Cross-check block hashes against a second source during suspected reorgs"],"tags":["blockchain","reorg","header-mismatch","consistency"],"backgroundTag":"checksum-mismatch","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"}