{"record":{"id":"c6693c843e348452","repo":"nautechsystems/nautilus_trader","slug":"execution-schema-version-is-newer-than-supporte","errorCode":null,"errorMessage":"Execution schema version {} is newer than supported version {EXECUTION_SCHEMA_VERSION}","messagePattern":"Execution schema version (.+?) is newer than supported version (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":3232,"sourceCode":"        ] {\n            sqlx::query(statement)\n                .execute(&mut *transaction)\n                .await\n                .map_err(|e| {\n                    anyhow::anyhow!(\"Failed to migrate execution_transaction table: {e}\")\n                })?;\n        }\n\n        let installed_version = sqlx::query_scalar::<_, i16>(\n            \"SELECT version FROM execution_schema_version WHERE component = 'evm_execution'\",\n        )\n        .fetch_optional(&mut *transaction)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to read execution schema version: {e}\"))?;\n        if let Some(installed_version) = installed_version\n            && installed_version > EXECUTION_SCHEMA_VERSION\n        {\n            anyhow::bail!(\n                \"Execution schema version {} is newer than supported version {EXECUTION_SCHEMA_VERSION}\",\n                installed_version\n            );\n        }\n\n        let unresolved_legacy = sqlx::query_scalar::<_, i64>(\n            \"\n            SELECT COUNT(*)\n            FROM execution_transaction\n            WHERE status IN ('pending', 'included', 'reverted')\n            \",\n        )\n        .fetch_one(&mut *transaction)\n        .await\n        .map_err(|e| anyhow::anyhow!(\"Failed to inspect legacy execution transactions: {e}\"))?;\n        anyhow::ensure!(\n            unresolved_legacy == 0,\n            \"Cannot safely migrate {unresolved_legacy} unresolved execution schema version 1 transaction(s); resolve them with the prior version before enabling version {EXECUTION_SCHEMA_VERSION}\"","sourceCodeStart":3214,"sourceCodeEnd":3250,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/2114cf6f761429e0adb5ca9596fcd7b895b16011/crates/adapters/blockchain/src/cache/database.rs#L3214-L3250","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: old binary, newer DB -> init bails\n// 'Execution schema version 3 is newer than supported version 2'\n\n// after: probe compatibility before starting the node\nlet v: Option<i16> = sqlx::query_scalar(\n    \"SELECT version FROM execution_schema_version WHERE component = 'evm_execution'\",\n)\n.fetch_optional(&pool).await?;\nanyhow::ensure!(\n    v.unwrap_or(0) <= 2,\n    'DB evm_execution schema {v:?} is newer than this build supports (2); upgrade nautilus_trader',\n);","handlingStrategy":"validation","validationCode":"let v: Option<i16> = sqlx::query_scalar(\n    \"SELECT version FROM execution_schema_version WHERE component = 'evm_execution'\",\n)\n.fetch_optional(&pool).await?;\nanyhow::ensure!(v.unwrap_or(0) <= EXECUTION_SCHEMA_VERSION_BUILD, 'DB schema newer than build; upgrade first');","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["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."],"tags":["rust","nautilustrader","postgres","schema-version","database-migration","blockchain"],"backgroundTag":"schema-version-mismatch","analyzedSha":"2114cf6f761429e0adb5ca9596fcd7b895b16011","analyzedAt":"2026-08-21T11:28:30.864Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}