{"record":{"id":"bf9bff89bc79c9e1","repo":"nautechsystems/nautilus_trader","slug":"finality-verification-disagreed-with-the-receipt-o","errorCode":null,"errorMessage":"Finality verification disagreed with the receipt or finalized header","messagePattern":"Finality verification disagreed with the receipt or finalized header","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":3494,"sourceCode":"            ));\n            finalized_headers.extend(ancestry.iter().copied());\n        }\n        anyhow::ensure!(\n            ancestry_cursor == finalized,\n            \"Finalized header conflicts with its verified ancestry\"\n        );\n\n        let canonical_again_verification = required_verification(\n            self.verification.verify_block(receipt.block_number).await,\n            \"finality inclusion header reread\",\n        )?;\n        let canonical_again = canonical_again_verification.value;\n        let finalized_again_verification = required_verification(\n            self.verification.verify_block(finalized.number).await,\n            \"finalized header reread\",\n        )?;\n        let finalized_again = finalized_again_verification.value;\n        anyhow::ensure!(\n            canonical_again.hash == receipt.block_hash && finalized_again == finalized,\n            \"Finality verification disagreed with the receipt or finalized header\"\n        );\n        decisions.extend([\n            verification_decision(\n                &finalized_verification,\n                Some(finalized.number),\n                Some(finalized.number),\n            ),\n            verification_decision(\n                &canonical_again_verification,\n                Some(receipt.block_number),\n                Some(receipt.block_number),\n            ),\n            verification_decision(\n                &finalized_again_verification,\n                Some(finalized.number),\n                Some(finalized.number),","sourceCodeStart":3476,"sourceCodeEnd":3512,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L3476-L3512","documentation":"As a final consistency pass, the client re-verifies both the receipt's canonical block and the finalized header. The check requires the re-read canonical hash to equal the receipt's block hash AND the re-read finalized header to equal the previously determined one. Any disagreement means the verification source changed its answer between reads or the receipt/header is inconsistent.","triggerScenarios":"During finality verification when `verify_block(receipt.block_number).hash != receipt.block_hash` or `verify_block(finalized.number) != finalized` — e.g. a reorg landed between the two verification passes, or a load-balanced RPC pool returned different-chain nodes.","commonSituations":"Unstable reorg churn at the canonical head; RPC endpoints behind a load balancer serving different backends/forks; provider bug returning inconsistent headers across calls.","solutions":["Pin all verification calls to a single consistent RPC node (disable mixed-node load balancing).","Log both verification results and retry after the chain stabilizes.","If a reorg is confirmed, restart finality verification from the checkpoint with refreshed state."],"exampleFix":"// before: two calls may hit different fork nodes\nlet canonical_again = self.verification.verify_block(receipt.block_number).await?;\n// after: pinned, consistent source\nlet canonical_again = self.pinned_verification().verify_block(receipt.block_number).await?;","handlingStrategy":"retry","validationCode":"let c1 = verification.verify_block(receipt.block_number).await?;\nlet c2 = verification.verify_block(receipt.block_number).await?;\nanyhow::ensure!(c1 == c2, \"verification source unstable between reads\");","typeGuard":null,"tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"disagreed with the receipt\") => {\n        backoff_then_retry_with_pinned_node()\n    }\n    other => other,\n}","preventionTips":["Pin RPC calls to one consistent node instead of load-balanced pools","Retry verification after short backoff during reorg churn","Log both read results to diagnose reorgs vs provider bugs"],"tags":["finality","verification","consistency","rpc"],"backgroundTag":"internal-invariant-violation","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"}