nautechsystems/nautilus_trader · error · anyhow::Error

Failed to start execution schema migration

Error message

Failed to start execution schema migration: {e}

What it means

This error wraps failure to begin a Postgres transaction (`pool.begin()`) at the start of the execution schema migration routine. The library throws it so callers know the schema upgrade could not even start, before any table locks or DDL ran.

Solutions

  1. Verify database connectivity and credentials with a simple SELECT 1
  2. Check pool configuration (max_connections, acquire_timeout) for exhaustion
  3. Retry after confirming the database is accepting connections
  4. Confirm the user has permission to start transactions on the database

Example fix

// before
.map_err(|e| anyhow::anyhow!("Failed to start execution schema migration: {e}"))?;
// after
.map_err(|e| {
    tracing::error!(error = %e, "cannot begin migration transaction");
    anyhow::anyhow!("Failed to start execution schema migration: {e}")
})?;
Defensive patterns

Strategy: retry

Validate before calling

let reachable = sqlx::query("SELECT 1").execute(&pool).await.is_ok();
if !reachable { anyhow::bail!("database unreachable; cannot run migration"); }

Try / catch

match db.ensure_execution_transaction_schema().await {
    Ok(()) => (),
    Err(e) if is_connection_error(&e) => { wait_for_db().await; retry_migration().await?; }
    Err(e) => return Err(e),
}

Prevention

When it happens

Trigger: ensure_execution_transaction_schema called while the database is unreachable, credentials are invalid, the pool is exhausted (checkout timeout), or the default isolation level is not supported by the backend.

Common situations: Postgres down or restarting during deployment; wrong DATABASE_URL; pool max_connections exhausted by other services; network partition between app and DB.

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/a8912bee5da3312e. Report an issue: GitHub.

Appendix: source

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

        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
            .pool
            .begin()
            .await
            .map_err(|e| anyhow::anyhow!("Failed to start execution schema migration: {e}"))?;

        sqlx::query("LOCK TABLE execution_transaction IN ACCESS EXCLUSIVE MODE")
            .execute(&mut *transaction)
            .await
            .map_err(|e| anyhow::anyhow!("Failed to lock legacy execution transactions: {e}"))?;

        for statement in [
            "
            ALTER TABLE execution_transaction
            ADD COLUMN IF NOT EXISTS client_order_id TEXT
            ",
            "
            ALTER TABLE execution_transaction
            ADD COLUMN IF NOT EXISTS wallet_address TEXT
            ",
            "
            ALTER TABLE execution_transaction
            ALTER COLUMN wallet_address DROP NOT NULL

View on GitHub (pinned to 18893faf8b)