{"record":{"id":"f9512a8cebd36dcc","repo":"nautechsystems/nautilus_trader","slug":"failed-to-persist-finality-verification-e","errorCode":null,"errorMessage":"Failed to persist finality verification: {e}","messagePattern":"Failed to persist finality verification: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":7108,"sourceCode":"                )\n                \",\n            )\n            .bind(finality.intent_id)\n            .bind(nonce)\n            .bind(decision.read_class)\n            .bind(height_start)\n            .bind(height_end)\n            .bind(finality.manifest_version)\n            .bind(finality.manifest_digest)\n            .bind(finality.provider_ids)\n            .bind(finality.operator_ids)\n            .bind(finality.failure_domain_ids)\n            .bind(&decision.normalized_value_digest)\n            .bind(revision)\n            .bind(transition_key)\n            .execute(&mut *transaction)\n            .await\n            .map_err(|e| anyhow::anyhow!(\"Failed to persist finality verification: {e}\"))?;\n        }\n\n        let hash_result = sqlx::query(\n            \"\n            UPDATE execution_transaction_hash\n            SET status = $3, block_number = $4, block_hash = $5,\n                receipt_success = $6, gas_used = $7, effective_gas_price = $8,\n                updated_at = NOW()\n            WHERE intent_id = $1 AND transaction_hash = $2\n            \",\n        )\n        .bind(finality.intent_id)\n        .bind(finality.transaction_hash)\n        .bind(finality.status.as_str())\n        .bind(block_number)\n        .bind(finality.block_hash)\n        .bind(finality.receipt_success)\n        .bind(gas_used)","sourceCodeStart":7090,"sourceCodeEnd":7126,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L7090-L7126","documentation":"Wraps a sqlx failure while INSERTing/UPSERTing a per-decision finality verification row (with failure_domain_ids, normalized_value_digest, revision, transition_key) into its verification table. The whole finality transaction rolls back, so nothing (headers, receipt, intent status) is committed. The root database error is embedded via `{e}`.","triggerScenarios":"The per-decision INSERT fails: unique conflict on transition_key for a replayed finality event, schema drift (missing columns), oversized failure_domain_ids array, connection loss, or bind type mismatch on the digest/revision fields.","commonSituations":"Re-applying the same transition_key after a partial retry; migrations out of sync between environments; Postgres array/bytea type changes after an upgrade; large decision batches exceeding statement or packet limits.","solutions":["Read the embedded `{e}` for the exact Postgres error (constraint, type, connection)","If it is a duplicate transition_key, the verification was already recorded — make the insert idempotent (ON CONFLICT DO NOTHING) or skip","Run pending migrations to align the verification table schema","Check bind parameter types/sizes (digest, revision, failure_domain_ids array) against column definitions"],"exampleFix":"// before\n.execute(&mut *transaction)\n.await\n.map_err(|e| anyhow::anyhow!(\"Failed to persist finality verification: {e}\"))?;\n// after\n.execute(&mut *transaction)\n.await\n.map_err(|e| anyhow::anyhow!(\"Failed to persist finality verification (intent={}, decision={index}): {e}\", finality.intent_id))?;","handlingStrategy":"validation","validationCode":"// Check whether this transition_key was already persisted\nlet seen = sqlx::query_scalar::<_, i64>(\n    \"SELECT COUNT(*) FROM execution_finality_verification WHERE transition_key = $1\"\n)\n.bind(&transition_key)\n.fetch_one(&mut *conn).await?;\nif seen > 0 { /* already recorded — skip */ }","typeGuard":null,"tryCatchPattern":"match persist_finality(...).await {\n    Err(e) if e.to_string().contains(\"duplicate key\") => Ok(()), // idempotent replay\n    Err(e) if is_transient_db_error(&e) => retry_with_backoff(3, || persist_finality(...)),\n    Err(e) => Err(e),\n    Ok(v) => Ok(v),\n}","preventionTips":["Make verification inserts idempotent with ON CONFLICT DO NOTHING on transition_key","Keep decision digests and revision types aligned with column definitions across migrations","Batch decisions within reasonable size limits","Test finality replay paths in staging to catch constraint conflicts"],"tags":["database","sqlx","persistence","finality"],"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"}