nautechsystems/nautilus_trader · critical · anyhow::Error

Execution verification schema version {installed_version} is

Error message

Execution verification schema version {installed_version} is newer than supported version {VERIFICATION_SCHEMA_VERSION}

What it means

The installed schema version recorded in execution_schema_version exceeds the VERIFICATION_SCHEMA_VERSION compiled into this binary. The code refuses to bootstrap because an older binary must not touch a newer schema layout, which could corrupt data or violate its invariants.

Source

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

        sqlx::query(
            "LOCK TABLE execution_intent, execution_transaction_hash, \
             execution_verification_nonce, execution_verified_finalized_header, \
             execution_verification_decision, execution_replacement_scan \
             IN ACCESS EXCLUSIVE MODE",
        )
        .execute(&mut *transaction)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to lock execution verification state: {e}"))?;

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

        let current = sqlx::query_as::<_, (String, String, i64, i64)>(
            "
            SELECT manifest_version, manifest_digest, next_canonical_nonce, revision
            FROM execution_verification_nonce
            WHERE chain_id = $1 AND wallet_address = $2
            FOR UPDATE
            ",
        )
        .bind(chain_id)
        .bind(bootstrap.wallet_address)
        .fetch_optional(&mut *transaction)
        .await
        .map_err(|e| anyhow::anyhow!("Failed to read canonical nonce ledger: {e}"))?;

View on GitHub (pinned to 18893faf8b)

Solutions

Deploy a build whose VERIFICATION_SCHEMA_VERSION is >= the installed version (roll forward, not back)
If rollback is intentional, restore a database snapshot taken before the newer migration
Do not hand-edit execution_schema_version; use the project's migration tooling
Pin the shared database to the same release channel as the binary

Example fix

// before: old binary against migrated DB
// installed_version=3, VERIFICATION_SCHEMA_VERSION=2 -> error
// after: roll forward to a binary supporting version 3
git checkout main && cargo build --release  # includes newest schema

Defensive patterns

Strategy: validation

Validate before calling

let v: Option<i16> = sqlx::query_scalar(
  "SELECT version FROM execution_schema_version
   WHERE component='evm_execution_verification'")
  .fetch_optional(&mut *conn).await?;
if let Some(v) = v {
    if v > VERIFICATION_SCHEMA_VERSION {
        panic!("DB schema v{v} > binary-supported v{VERIFICATION_SCHEMA_VERSION}; roll forward");
    }
}

Try / catch

match bootstrap_verification(&mut tx).await {
    Err(e) if e.to_string().contains("newer than supported version") => {
        error!(%e, "database schema is ahead of this binary; refuse to start");
        std::process::exit(exitcode::CONFIGURATION); // fail fast, never downgrade-write
    }
    other => other,
}

Prevention

Never roll back deployments without a matching DB snapshot/rollback plan
Keep schema version checks in a startup preflight that fails fast
Use migrations that only move forward; make binaries backward-compatible or refuse to start
Coordinate shared dev databases with the release that migrates them

When it happens

Trigger: executing the bootstrap after the database was migrated by a newer application build: installed_version > VERIFICATION_SCHEMA_VERSION in execution_schema_version for component 'evm_execution_verification'.

Common situations: Rolling back a deployment to an older image/tag against a database already migrated forward; a canary or staging environment upgraded the shared database; rebuilding an old git commit against a current dev database.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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