{"record":{"id":"fb12d6aaccf80166","repo":"nautechsystems/nautilus_trader","slug":"execution-intent-uses-unsupported-schema-versio","errorCode":null,"errorMessage":"Execution intent {} uses unsupported schema version {}","messagePattern":"Execution intent (.+?) uses unsupported schema version (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":918,"sourceCode":"            fee,\n            amount_in,\n            min_amount_out: U256::ZERO,\n            profiler_block: intent.created_block,\n        })\n    }\n\n    async fn reconcile_unresolved_execution(&self) -> anyhow::Result<()> {\n        let database = self.cache.database.clone().ok_or_else(|| {\n            anyhow::anyhow!(\"No durable store configured for execution reconciliation\")\n        })?;\n        let wallet_address = self.wallet_address.to_string();\n        let Some(intent) = database\n            .get_active_execution_intent(self.chain.chain_id, &wallet_address)\n            .await?\n        else {\n            return Ok(());\n        };\n        anyhow::ensure!(\n            intent.schema_version == crate::execution::transaction::EXECUTION_SCHEMA_VERSION,\n            \"Execution intent {} uses unsupported schema version {}\",\n            intent.id,\n            intent.schema_version\n        );\n\n        if matches!(intent.status.as_str(), \"prepared\" | \"signed\") {\n            database\n                .mark_execution_intent_recoverable(intent.id)\n                .await?;\n            release_preparing_slot(&self.in_flight);\n            return Ok(());\n        }\n\n        let purpose = TransactionPurpose::parse(&intent.purpose).ok_or_else(|| {\n            anyhow::anyhow!(\n                \"Execution intent {} has unknown purpose {}\",\n                intent.id,","sourceCodeStart":900,"sourceCodeEnd":936,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/2114cf6f761429e0adb5ca9596fcd7b895b16011/crates/adapters/blockchain/src/execution/client.rs#L900-L936","documentation":"Thrown by reconcile_unresolved_execution during client startup: the durable (PostgreSQL) execution_intent row that is still active for this chain and wallet was written with a schema_version that does not equal the EXECUTION_SCHEMA_VERSION constant (currently 2) compiled into this build. The reconciler refuses to interpret intent rows from a different schema generation because the persisted field semantics may have changed. It surfaces as a connect() failure before any trading starts.","triggerScenarios":"Calling connect() while the execution_intent table holds a row with active = TRUE for the configured chain_id and wallet_address whose schema_version differs from 2 (e.g. an intent persisted by an older or newer NautilusTrader build during a schema bump). The check is an anyhow::ensure! comparing intent.schema_version to crate::execution::transaction::EXECUTION_SCHEMA_VERSION.","commonSituations":"Upgrading or downgrading the blockchain adapter crate while a swap intent was broadcast but not yet finalized; reusing a production Postgres store with a dev build from a different version; two NautilusTrader versions pointing at the same database.","solutions":["Check the stored row: SELECT id, schema_version, status, active FROM execution_intent WHERE chain_id = <chain> AND wallet_address = '<0x...>' AND active;","If the intent was written by the older schema, either finish reconciliation with the binary version that wrote it, or archive the row (back it up and set active = FALSE) so startup can proceed","Run any provided schema migration for the execution tables before reconnecting after an upgrade","For dev/test stores, point the client at a fresh postgres_cache_database_config instead of a store carrying foreign-version rows"],"exampleFix":"-- before: stale row blocks startup\nSELECT id, schema_version FROM execution_intent WHERE active;\n-- id=42, schema_version=1\n\n-- after: archive the incompatible intent after verifying no funds are at risk\nUPDATE execution_intent SET active = FALSE WHERE id = 42 AND schema_version <> 2;","handlingStrategy":"validation","validationCode":"-- Run before starting the trader, against the configured Postgres store\nSELECT id, schema_version, status\nFROM execution_intent\nWHERE chain_id = :chain_id\n  AND wallet_address = :wallet\n  AND active\n  AND schema_version <> 2;  -- current EXECUTION_SCHEMA_VERSION\n-- Any row here means connect() will fail with the schema-version error.","typeGuard":null,"tryCatchPattern":"try:\n    client.connect()\nexcept Exception as e:\n    if 'unsupported schema version' in str(e):\n        # halt: reconcile or archive the stale intent row before retrying\n        raise RuntimeError(f'Stale execution intent schema: {e}')\n    raise","preventionTips":["Drain all active intents (let swaps finalize) before upgrading or downgrading the blockchain adapter","Keep one Postgres store per NautilusTrader version during migrations; cut over only after active intents settle","Treat the execution tables as client-owned: no external writers"],"tags":["blockchain","reconciliation","schema-version","postgres","startup"],"backgroundTag":"schema-version-mismatch","analyzedSha":"2114cf6f761429e0adb5ca9596fcd7b895b16011","analyzedAt":"2026-08-21T11:28:30.864Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}