{"record":{"id":"53499b74ce978cea","repo":"nautechsystems/nautilus_trader","slug":"failed-to-initialize-finalized-header-ledger-e","errorCode":null,"errorMessage":"Failed to initialize finalized header ledger: {e}","messagePattern":"Failed to initialize finalized header ledger: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":4390,"sourceCode":"            INSERT INTO execution_verified_finalized_header (\n                chain_id, wallet_address, number, hash, parent_hash, timestamp,\n                base_fee_per_gas, manifest_digest\n            )\n            VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n            ON CONFLICT (chain_id, wallet_address, number) DO NOTHING\n            \",\n        )\n        .bind(chain_id)\n        .bind(bootstrap.wallet_address)\n        .bind(checkpoint_number)\n        .bind(bootstrap.checkpoint_hash)\n        .bind(bootstrap.checkpoint_parent_hash)\n        .bind(checkpoint_timestamp)\n        .bind(base_fee)\n        .bind(bootstrap.manifest_digest)\n        .execute(&mut *transaction)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to initialize finalized header ledger: {e}\"))?;\n        let stored_checkpoint = sqlx::query_as::<_, (String, String, i64, Option<String>)>(\n            \"\n            SELECT hash, parent_hash, timestamp, base_fee_per_gas\n            FROM execution_verified_finalized_header\n            WHERE chain_id = $1 AND wallet_address = $2 AND number = $3\n            \",\n        )\n        .bind(chain_id)\n        .bind(bootstrap.wallet_address)\n        .bind(checkpoint_number)\n        .fetch_one(&mut *transaction)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to validate finalized checkpoint ledger: {e}\"))?;\n        anyhow::ensure!(\n            stored_checkpoint\n                == (\n                    bootstrap.checkpoint_hash.to_string(),\n                    bootstrap.checkpoint_parent_hash.to_string(),","sourceCodeStart":4372,"sourceCodeEnd":4408,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L4372-L4408","documentation":"This error wraps a sqlx failure on the INSERT that seeds the `execution_verified_finalized_header` ledger with the trusted checkpoint header (ON CONFLICT DO NOTHING). The bootstrap path writes the checkpoint row inside a transaction before validating it; any database-level failure on that INSERT is re-raised with this message and aborts ledger initialization.","triggerScenarios":"During finalized-ledger bootstrap when the checkpoint INSERT fails: table `execution_verified_finalized_header` missing or schema-drifted, i64 bind of checkpoint_number/timestamp/base_fee out of range, connection/pool failure, or the transaction already aborted from an earlier step.","commonSituations":"Deploying a new version of the adapter against an un-migrated database; checkpoint height or base-fee values that exceed BIGINT; transient Postgres restarts or timeouts; wrong database_url pointing at a database without the verified-header tables.","solutions":["Apply the crate's schema migrations so `execution_verified_finalized_header` exists with columns (chain_id, wallet_address, number, hash, parent_hash, timestamp, base_fee_per_gas, manifest_digest).","Read the wrapped sqlx error after the colon for the root cause (undefined table, out-of-range value, connection error).","Confirm checkpoint_number and checkpoint_timestamp fit into i64 before bootstrapping.","Check database connectivity, credentials, and pool configuration.","Retry initialization after a transient failure — the ON CONFLICT DO NOTHING makes re-runs idempotent."],"exampleFix":"// before\n.execute(&mut *transaction)\n.await\n.map_err(|e| anyhow::anyhow!(\"Failed to initialize finalized header ledger: {e}\"))?;\n\n// after\n.execute(&mut *transaction)\n.await\n.map_err(|e| {\n    anyhow::anyhow!(\n        \"Failed to initialize finalized header ledger at number {checkpoint_number}: {e:#}\"\n    )\n})?;","handlingStrategy":"retry","validationCode":"// Verify schema readiness before bootstrap\nlet ready: bool = sqlx::query_scalar(\n    \"SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name='execution_verified_finalized_header')\",\n).fetch_one(&pool).await?;\nanyhow::ensure!(ready, \"verified header table missing; run migrations\");\nanyhow::ensure!(\n    bootstrap.checkpoint_number <= i64::MAX as u64,\n    \"checkpoint number exceeds BIGINT\"\n);","typeGuard":null,"tryCatchPattern":"match bootstrap_result {\n    Err(e) if is_transient_db_error(&e) => {\n        warn!(\"transient DB error, retrying bootstrap: {e:#}\");\n        backoff_retry(|| initialize_ledger(...), 3);\n    }\n    Err(e) => return Err(e),\n    Ok(v) => Ok(v),\n}","preventionTips":["Run schema migrations before starting the adapter","Use ON CONFLICT DO NOTHING semantics (already built-in) so retries are safe","Confirm checkpoint number/timestamp fit PostgreSQL BIGINT","Pin a healthy database_url and validate connectivity at startup"],"tags":["database","sqlx","postgres","bootstrap"],"backgroundTag":"database-write-failed","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"}