{"record":{"id":"3d43df7df218303d","repo":"nautechsystems/nautilus_trader","slug":"durable-finalized-header-tip-precedes-the-trusted","errorCode":null,"errorMessage":"Durable finalized header tip precedes the trusted checkpoint","messagePattern":"Durable finalized header tip precedes the trusted checkpoint","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":3433,"sourceCode":"        )?;\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\n            .database\n            .load_execution_verification_position(\n                self.chain_id,\n                &self.wallet_address.to_string(),\n                &self.manifest_version,\n                &self.manifest_digest,\n            )\n            .await?\n            .ok_or_else(|| anyhow::anyhow!(\"Execution verification ledger is not initialized\"))?;\n        let durable_tip = parse_verified_header(&position.finalized_tip)?;\n        anyhow::ensure!(\n            durable_tip.number >= checkpoint.number,\n            \"Durable finalized header tip precedes the trusted checkpoint\"\n        );\n        let mut finalized_headers = vec![durable_tip];\n        let durable_tip_verification = required_verification(\n            self.verification.verify_block(durable_tip.number).await,\n            \"finality durable header tip\",\n        )?;\n        anyhow::ensure!(\n            durable_tip_verification.value == durable_tip,\n            \"Durable finalized header tip conflicts with independent sources\"\n        );\n        decisions.push(verification_decision(\n            &durable_tip_verification,\n            Some(durable_tip.number),\n            Some(durable_tip.number),\n        ));\n        anyhow::ensure!(","sourceCodeStart":3415,"sourceCodeEnd":3451,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L3415-L3451","documentation":"The execution client recovered its durable finalized tip from the verification ledger, but the stored header's block number is lower than the trusted checkpoint the run is anchored to. NautilusTrader requires durable finality to be at least as advanced as the checkpoint, so a stale or rolled-back ledger means the durable state cannot safely supplement checkpoint trust and the operation is aborted.","triggerScenarios":"Calling transaction finality recovery when the verification ledger row `finalized_tip` holds a header whose number < the checkpoint number — typically after restoring an older ledger snapshot, a partial ledger write/rollback, or pointing the client at a database populated against a different (older) checkpoint.","commonSituations":"Failover to a replica with a lagging verification ledger; restoring a DB backup from before the checkpoint was advanced; mixing ledger state from a previous deployment with a newer configured trusted checkpoint; ledger pruning that removed recent finalized headers.","solutions":["Inspect the verification ledger's finalized tip and compare its block number to the configured trusted checkpoint.","Rebuild or resync the verification ledger so its finalized tip is at or beyond the checkpoint (e.g. replay finalized headers from the RPC provider).","Re-run the recovery after the ledger has caught up, or re-anchor the run at an older checkpoint consistent with the ledger."],"exampleFix":"// before: checkpoint ahead of ledger state\nlet checkpoint = load_checkpoint(); // # 1_000\n// ledger finalized_tip.number == 900 -> ensure! fails\n// after: resync ledger, then verify before recovery\nensure_durable_tip_covers_checkpoint(&ledger, &checkpoint)?; // tip >= checkpoint","handlingStrategy":"validation","validationCode":"// before recovery, assert ledger covers checkpoint\nlet tip_number = ledger.finalized_tip_number()?;\nanyhow::ensure!(tip_number >= checkpoint.number, \"ledger tip {} < checkpoint {}\", tip_number, checkpoint.number);","typeGuard":null,"tryCatchPattern":"match client.recover_finality(&checkpoint).await {\n    Err(e) if e.to_string().contains(\"precedes the trusted checkpoint\") => resync_ledger_and_retry(),\n    Err(e) => return Err(e),\n    Ok(v) => Ok(v),\n}","preventionTips":["Resync the verification ledger whenever the checkpoint is advanced","Never restore ledger snapshots older than the configured checkpoint","Add a startup health check comparing ledger tip vs checkpoint"],"tags":["finality","consistency","blockchain","persistence"],"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"}