nautechsystems/nautilus_trader · error · anyhow::Error

Execution transaction

Error message

Execution transaction {transaction_hash} conflicts with its persisted record

What it means

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.

Solutions

  1. Query for an existing row with the same transaction_hash and compare status before inserting
  2. Use INSERT ... ON CONFLICT with an explicit update/idempotency policy instead of relying on affected-row count
  3. Log transaction_hash and rows_affected to diagnose why the insert was not applied
  4. Ensure only one writer process inserts execution transactions for a given hash

Example fix

// before
anyhow::ensure!(
    result.rows_affected() == 1,
    "Execution transaction {transaction_hash} conflicts with its persisted record"
);
// after
if result.rows_affected() != 1 {
    let existing = sqlx::query("SELECT status FROM execution_transaction WHERE transaction_hash = $1")
        .bind(transaction_hash)
        .fetch_optional(&self.pool)
        .await?;
    tracing::warn!(existing = ?existing.map(|r| r.get::<_, String>("status")), %transaction_hash, "insert conflict");
    anyhow::bail!("Execution transaction {transaction_hash} conflicts with its persisted record");
}
Defensive patterns

Strategy: fallback

Validate before calling

let existing = sqlx::query("SELECT 1 FROM execution_transaction WHERE transaction_hash = $1")
    .bind(&tx_hash)
    .fetch_optional(&pool)
    .await?;
if existing.is_some() { /* reconcile or skip before inserting */ }

Try / catch

match insert(tx).await {
    Ok(()) => (),
    Err(e) if e.to_string().contains("conflicts with its persisted record") => {
        reconcile_with_persisted_record(tx).await?;
    }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: 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.

Common situations: Retrying an insert for the same transaction hash after a partial failure; concurrent writers inserting the same transaction; schema triggers that filter rows.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors


AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/a81106ec9a7a8ef5. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/blockchain/src/cache/database.rs:3333

            WHERE execution_transaction.wallet_address = EXCLUDED.wallet_address
              AND execution_transaction.nonce = EXCLUDED.nonce
              AND execution_transaction.purpose = EXCLUDED.purpose
              AND execution_transaction.status = EXCLUDED.status
              AND execution_transaction.client_order_id IS NOT DISTINCT FROM EXCLUDED.client_order_id
        ",
        )
        .bind(chain_id as i32)
        .bind(wallet_address)
        .bind(nonce as i64)
        .bind(transaction_hash)
        .bind(purpose)
        .bind(status)
        .bind(client_order_id)
        .execute(&self.pool)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to insert into execution_transaction table: {e}"))?;

        anyhow::ensure!(
            result.rows_affected() == 1,
            "Execution transaction {transaction_hash} conflicts with its persisted record"
        );
        Ok(())
    }

    /// Installs execution schema version 2 without changing existing transaction rows.
    ///
    /// The migration locks the legacy transaction table, refuses unresolved version 1 rows,
    /// installs the versioned intent and hash-history tables, and fences older writers before
    /// releasing the lock. This prevents a mixed-version process from bypassing the new signer
    /// ownership constraints.
    ///
    /// # Errors
    ///
    /// Returns an error if the database operation fails.
    pub async fn ensure_execution_transaction_schema(&self) -> anyhow::Result<()> {
        let mut transaction = self

View on GitHub (pinned to 18893faf8b)