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
- 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
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
- 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
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
- Account not found after cache update
- Account event does not exist for account
- Active execution intent
- Active finality intent was not found
- Active replacement scan intent was not found
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 = selfView on GitHub (pinned to 18893faf8b)