{"record":{"id":"d5ad8e5d6b609958","repo":"nautechsystems/nautilus_trader","slug":"finalized-header-verification-is-locally-invalid","errorCode":null,"errorMessage":"Finalized header verification is locally invalid","messagePattern":"Finalized header verification is locally invalid","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":3404,"sourceCode":"        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),\n            Some(checkpoint.number),\n        )];\n        let position = self","sourceCodeStart":3386,"sourceCodeEnd":3422,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L3386-L3422","documentation":"Same verification flow as the finalized-header disagreement case, but here the outcome is LocallyInvalid: the verified finalized header itself fails local validation (malformed or self-inconsistent data). The client bails because it cannot establish a trustworthy finalized height.","triggerScenarios":"verify_finalized_header() returns LocallyInvalid during the receipt finality check — typically corrupted or inconsistent header data from the verification source (bad fields, impossible values, failed local invariants).","commonSituations":"Corrupted local consensus data/cache; buggy or outdated verification source version; provider returning malformed headers after an upstream upgrade.","solutions":["Clear and rebuild the consensus/verification cache and retry","Update the verification source/checkpoint data to the current network version","Confirm the provider serves well-formed headers (compare against a second endpoint)","Check the library version is compatible with the network's current header format"],"exampleFix":"// before: stale cached consensus data reused\n// after: force refresh of verification state before finality checks\nverification.refresh_checkpoints().await?;\nlet finalized = verification.verify_finalized_header().await?;","handlingStrategy":"fallback","validationCode":"let header = verification.verify_finalized_header().await?;\ndebug_assert!(header.value.number > 0 && header.value.parent_hash != Default::default(), \"malformed finalized header\");","typeGuard":null,"tryCatchPattern":"match res {\n    Err(e) if e.to_string().contains(\"locally invalid\") => {\n        verification.rebuild_state().await?;\n        retry_verification().await?;\n    }\n    other => other?,\n}","preventionTips":["Keep the consensus verification cache healthy and rebuildable","Update library/checkpoint versions after network upgrades","Validate headers against a second endpoint before trusting them","Fail closed: never treat unverifiable finality as confirmed"],"tags":["blockchain","verification","finality","consensus"],"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"}