{"record":{"id":"a81106ec9a7a8ef5","repo":"nautechsystems/nautilus_trader","slug":"execution-transaction-transaction-hash-conflicts","errorCode":null,"errorMessage":"Execution transaction {transaction_hash} conflicts with its persisted record","messagePattern":"Execution transaction (.+?) conflicts with its persisted record","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":3333,"sourceCode":"            WHERE execution_transaction.wallet_address = EXCLUDED.wallet_address\n              AND execution_transaction.nonce = EXCLUDED.nonce\n              AND execution_transaction.purpose = EXCLUDED.purpose\n              AND execution_transaction.status = EXCLUDED.status\n              AND execution_transaction.client_order_id IS NOT DISTINCT FROM EXCLUDED.client_order_id\n        \",\n        )\n        .bind(chain_id as i32)\n        .bind(wallet_address)\n        .bind(nonce as i64)\n        .bind(transaction_hash)\n        .bind(purpose)\n        .bind(status)\n        .bind(client_order_id)\n        .execute(&self.pool)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to insert into execution_transaction table: {e}\"))?;\n\n        anyhow::ensure!(\n            result.rows_affected() == 1,\n            \"Execution transaction {transaction_hash} conflicts with its persisted record\"\n        );\n        Ok(())\n    }\n\n    /// Installs execution schema version 2 without changing existing transaction rows.\n    ///\n    /// The migration locks the legacy transaction table, refuses unresolved version 1 rows,\n    /// installs the versioned intent and hash-history tables, and fences older writers before\n    /// releasing the lock. This prevents a mixed-version process from bypassing the new signer\n    /// ownership constraints.\n    ///\n    /// # Errors\n    ///\n    /// Returns an error if the database operation fails.\n    pub async fn ensure_execution_transaction_schema(&self) -> anyhow::Result<()> {\n        let mut transaction = self","sourceCodeStart":3315,"sourceCodeEnd":3351,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L3315-L3351","documentation":"This error is raised by anyhow::ensure! when the INSERT into execution_transaction reports rows_affected() != 1, meaning the write did not insert exactly one row. The library treats this as a conflict between the in-memory execution transaction and its persisted record, indicating an inconsistent state rather than a normal error.","triggerScenarios":"An INSERT ... ON CONFLICT DO NOTHING variant (or similar) silently skipping a duplicate transaction_hash, triggers/rules suppressing the insert, or an unexpected driver behavior where zero rows are affected.","commonSituations":"Retrying an insert for the same transaction hash after a partial failure; concurrent writers inserting the same transaction; schema triggers that filter rows.","solutions":["Query for an existing row with the same transaction_hash and compare status before inserting","Use INSERT ... ON CONFLICT with an explicit update/idempotency policy instead of relying on affected-row count","Log transaction_hash and rows_affected to diagnose why the insert was not applied","Ensure only one writer process inserts execution transactions for a given hash"],"exampleFix":"// before\nanyhow::ensure!(\n    result.rows_affected() == 1,\n    \"Execution transaction {transaction_hash} conflicts with its persisted record\"\n);\n// after\nif result.rows_affected() != 1 {\n    let existing = sqlx::query(\"SELECT status FROM execution_transaction WHERE transaction_hash = $1\")\n        .bind(transaction_hash)\n        .fetch_optional(&self.pool)\n        .await?;\n    tracing::warn!(existing = ?existing.map(|r| r.get::<_, String>(\"status\")), %transaction_hash, \"insert conflict\");\n    anyhow::bail!(\"Execution transaction {transaction_hash} conflicts with its persisted record\");\n}","handlingStrategy":"fallback","validationCode":"let existing = sqlx::query(\"SELECT 1 FROM execution_transaction WHERE transaction_hash = $1\")\n    .bind(&tx_hash)\n    .fetch_optional(&pool)\n    .await?;\nif existing.is_some() { /* reconcile or skip before inserting */ }","typeGuard":null,"tryCatchPattern":"match insert(tx).await {\n    Ok(()) => (),\n    Err(e) if e.to_string().contains(\"conflicts with its persisted record\") => {\n        reconcile_with_persisted_record(tx).await?;\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Check for an existing record with the same transaction_hash before inserting","Single-writer discipline: one process inserts a given transaction hash","Make retries idempotent so duplicate inserts are reconciled, not conflicting"],"tags":["database","constraint","state-conflict"],"backgroundTag":"invalid-state-transition","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}