nautechsystems/nautilus_trader · error · anyhow::Error

Execution schema version {} is newer than supported version

Error message

Execution schema version {} is newer than supported version {EXECUTION_SCHEMA_VERSION}

What it means

During blockchain cache initialization the client compares the Postgres row `execution_schema_version` for component 'evm_execution' against the compiled-in `EXECUTION_SCHEMA_VERSION` (currently 2). If the database was written by a newer build, initialization refuses to run rather than risk misinterpreting rows it does not understand. This is a forward-compatibility guard, not a corruption signal.

Source

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

        ] {
            sqlx::query(statement)
                .execute(&mut *transaction)
                .await
                .map_err(|e| {
                    anyhow::anyhow!("Failed to migrate execution_transaction table: {e}")
                })?;
        }

        let installed_version = sqlx::query_scalar::<_, i16>(
            "SELECT version FROM execution_schema_version WHERE component = 'evm_execution'",
        )
        .fetch_optional(&mut *transaction)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to read execution schema version: {e}"))?;
        if let Some(installed_version) = installed_version
            && installed_version > EXECUTION_SCHEMA_VERSION
        {
            anyhow::bail!(
                "Execution schema version {} is newer than supported version {EXECUTION_SCHEMA_VERSION}",
                installed_version
            );
        }

        let unresolved_legacy = sqlx::query_scalar::<_, i64>(
            "
            SELECT COUNT(*)
            FROM execution_transaction
            WHERE status IN ('pending', 'included', 'reverted')
            ",
        )
        .fetch_one(&mut *transaction)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to inspect legacy execution transactions: {e}"))?;
        anyhow::ensure!(
            unresolved_legacy == 0,
            "Cannot safely migrate {unresolved_legacy} unresolved execution schema version 1 transaction(s); resolve them with the prior version before enabling version {EXECUTION_SCHEMA_VERSION}"

View on GitHub (pinned to 2114cf6f76)

Solutions

Upgrade nautilus_trader to at least the version that wrote the database (the supported version is printed in the message).
Or point the client at a database whose schema version is at or below the supported one.
For a disposable dev database, drop the execution schema tables (or recreate the DB) — this loses execution history.
Pin one database per node version and never share a DB across mixed versions.

Example fix

// before: old binary, newer DB -> init bails
// 'Execution schema version 3 is newer than supported version 2'

// after: probe compatibility before starting the node
let v: Option<i16> = sqlx::query_scalar(
    "SELECT version FROM execution_schema_version WHERE component = 'evm_execution'",
)
.fetch_optional(&pool).await?;
anyhow::ensure!(
    v.unwrap_or(0) <= 2,
    'DB evm_execution schema {v:?} is newer than this build supports (2); upgrade nautilus_trader',
);

Defensive patterns

Strategy: validation

Validate before calling

let v: Option<i16> = sqlx::query_scalar(
    "SELECT version FROM execution_schema_version WHERE component = 'evm_execution'",
)
.fetch_optional(&pool).await?;
anyhow::ensure!(v.unwrap_or(0) <= EXECUTION_SCHEMA_VERSION_BUILD, 'DB schema newer than build; upgrade first');

Try / catch

Match the anyhow error at startup and fail the deployment with an actionable message ('database written by newer nautilus; upgrade or repoint DB') rather than retrying — retry cannot fix a version gap.

Prevention

Pin one Postgres database per nautilus version.
Probe the schema version in deployment preflight before starting the node.
Never downgrade binaries against a migrated database without recreating it.

When it happens

Trigger: Starting the blockchain execution client (an older nautilus build) against a Postgres database previously migrated by a newer version whose evm_execution schema version is greater than the compiled one — e.g. after downgrading nautilus_trader or rolling back a deployment.

Common situations: Downgrading the nautilus package after testing a newer release; sharing one Postgres instance between nodes running different versions; restoring a production backup onto a dev machine with an older build.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@2114cf6f76 (2026-08-21). Data as JSON: /api/errors/c6693c843e348452. Report an issue: GitHub.