nautechsystems/nautilus_trader · error

Failed to lock recoverable execution intent

Error message

Failed to lock recoverable execution intent: {e}

What it means

Immediately after starting the transaction, the function runs `SELECT status FROM execution_intent WHERE id = $1 FOR UPDATE` to lock the intent row. If that query fails at the database level (connection drop, lock timeout, server error), the sqlx error is wrapped as this message. A missing row is reported separately as 'Execution intent {id} was not found'.

Solutions

  1. Retry the call after the transient condition clears — the transaction rolled back so no partial state persists.
  2. Check for competing transactions holding `FOR UPDATE` locks on `execution_intent` and shorten them.
  3. Raise or remove a restrictive `lock_timeout` on the session/database if legitimate contention is expected.
  4. Verify connection stability (keepalives, pool health) between the app and PostgreSQL.

Example fix

// before: single attempt, hard failure
if let Err(e) = db.mark_execution_intent_recoverable(intent_id).await { return Err(e); }
// after: retry on lock-related failures
match db.mark_execution_intent_recoverable(intent_id).await {
    Ok(()) => {},
    Err(e) if e.to_string().contains("lock") => {
        tokio::time::sleep(Duration::from_secs(1)).await;
        db.mark_execution_intent_recoverable(intent_id).await?;
    }
    Err(e) => return Err(e),
}
Defensive patterns

Strategy: retry

Validate before calling

let exists = sqlx::query_scalar::<_, String>("SELECT status FROM execution_intent WHERE id=$1").bind(intent_id).fetch_optional(&pool).await?;
if exists.is_none() { return Err(anyhow!("intent {intent_id} does not exist")); }

Try / catch

match db.mark_execution_intent_recoverable(id).await {
    Err(e) if e.to_string().contains("Failed to lock recoverable execution intent") => { tokio::time::sleep(Duration::from_millis(500)).await; db.mark_execution_intent_recoverable(id).await?; }
    Err(e) => return Err(e),
    Ok(()) => {},
}

Prevention

When it happens

Trigger: Calling `mark_execution_intent_recoverable` while the connection dies mid-query, the row lock cannot be acquired within the server's lock_timeout, or the PostgreSQL server returns an error during the `FOR UPDATE` select.

Common situations: Another long transaction holds the `execution_intent` row lock past `lock_timeout`; the network drops between `begin()` and the select; a failover terminates the session after the transaction started.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors


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

Appendix: source

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

        Ok(())
    }

    /// Releases an intent when no broadcast attempt can have occurred.
    ///
    /// # Errors
    ///
    /// Returns an error if the intent advanced to broadcast or persistence fails.
    pub async fn mark_execution_intent_recoverable(&self, intent_id: i64) -> anyhow::Result<()> {
        let mut transaction = self.pool.begin().await.map_err(|e| {
            anyhow::anyhow!("Failed to start recoverable execution transition: {e}")
        })?;
        let current_status = sqlx::query_scalar::<_, String>(
            "SELECT status FROM execution_intent WHERE id = $1 FOR UPDATE",
        )
        .bind(intent_id)
        .fetch_optional(&mut *transaction)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to lock recoverable execution intent: {e}"))?
        .ok_or_else(|| anyhow::anyhow!("Execution intent {intent_id} was not found"))?;
        anyhow::ensure!(
            current_status == "prepared",
            "Execution intent {intent_id} is {current_status}, not recoverable before signing"
        );
        let result = sqlx::query(
            "
            UPDATE execution_intent
            SET status = 'recoverable', active = FALSE, updated_at = NOW()
            WHERE id = $1 AND status = 'prepared'
            ",
        )
        .bind(intent_id)
        .execute(&mut *transaction)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to mark execution intent recoverable: {e}"))?;
        anyhow::ensure!(
            result.rows_affected() == 1,

View on GitHub (pinned to 18893faf8b)