{"record":{"id":"46cf55794654bbd7","repo":"nautechsystems/nautilus_trader","slug":"finalized-header-verification-disagreed","errorCode":null,"errorMessage":"Finalized header verification disagreed","messagePattern":"Finalized header verification disagreed","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":3401,"sourceCode":"                None,\n            )\n            .await?;\n        Ok(InclusionOutcome::Pending(format!(\n            \"Timed out awaiting finality of transaction {tx_hash}; the intent stays occupied for reconciliation\"\n        )))\n    }\n\n    async fn receipt_is_stably_finalized(\n        &self,\n        receipt: &RpcTransactionReceipt,\n    ) -> anyhow::Result<Option<StableFinality>> {\n        let finalized_verification = match self.verification.verify_finalized_header().await {\n            VerificationOutcome::Verified(verified) => verified,\n            VerificationOutcome::Retryable(_) | VerificationOutcome::Unavailable(_) => {\n                return Ok(None);\n            }\n            VerificationOutcome::Disagreement(_) => {\n                anyhow::bail!(\"Finalized header verification disagreed\")\n            }\n            VerificationOutcome::LocallyInvalid(_) => {\n                anyhow::bail!(\"Finalized header verification is locally invalid\")\n            }\n        };\n        let finalized = finalized_verification.value;\n        if finalized.number < receipt.block_number {\n            return Ok(None);\n        }\n\n        let checkpoint_verification = required_verification(\n            self.verification.verify_checkpoint().await,\n            \"finality checkpoint reread\",\n        )?;\n        let checkpoint = checkpoint_verification.value;\n        let mut decisions = vec![verification_decision(\n            &checkpoint_verification,\n            Some(checkpoint.number),","sourceCodeStart":3383,"sourceCodeEnd":3419,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L3383-L3419","documentation":"The consensus verification layer returned VerificationOutcome::Disagreement for the finalized header check: the locally computed/verified finalized header conflicts with the authoritative source. The client treats this as a hard failure — it cannot trust the finalized chain view for receipt finality decisions.","triggerScenarios":"Calling the finalized-receipt verification flow when verify_finalized_header() yields a Disagreement — consensus checkpoint mismatch, divergent fork, or the verification source disagrees with the node's finalized block.","commonSituations":"Node syncing to a different fork; misconfigured consensus/checkpoint source; provider serving a chain that disagrees with the light-client verification data; mixed network endpoints (mainnet vs testnet).","solutions":["Check the node and verification source are on the same network and fork choice","Update/re-sync the consensus checkpoint data","Restart or resync the execution node if it followed a minority fork","Verify provider configuration (correct chain, no caching proxy serving stale headers)"],"exampleFix":"// before: mismatched endpoints\nlet exec = ExecutionClient::new(exec_rpc, verify_source_for_testnet);\n// after: consistent chain sources\nlet exec = ExecutionClient::new(exec_rpc, verify_source_for_mainnet);","handlingStrategy":"fallback","validationCode":"let local_finalized = rpc.finalized_block().await?;\nlet verified = verification.verify_finalized_header().await?;\nassert_eq!(local_finalized.hash, verified.value.hash, \"finalized header mismatch\");","typeGuard":null,"tryCatchPattern":"match res {\n    Err(e) if e.to_string().contains(\"verification disagreed\") => {\n        halt_trading(); // do not act on untrusted finality\n        alert_consensus_divergence();\n    }\n    other => other?,\n}","preventionTips":["Ensure execution node and consensus source target the same network and fork","Keep checkpoint data current","Cross-check finalized hashes between two independent endpoints","Halt finality-dependent actions on any disagreement rather than proceeding"],"tags":["blockchain","consensus","finality","verification"],"backgroundTag":"checksum-mismatch","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}