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
- Verify database connectivity and credentials with a simple SELECT 1
- Check pool configuration (max_connections, acquire_timeout) for exhaustion
- Retry after confirming the database is accepting connections
- 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
- Run migrations once at startup with retries and backoff
- Verify DATABASE_URL and credentials before deploying
- Ensure pool acquire_timeout is sufficient
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
- Cannot safely migrate
- Execution intent was not found
- Execution payload changed during migration
- Execution payload migration found
- Execution payload migration state is missing
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 NULLView on GitHub (pinned to 18893faf8b)