nautechsystems/nautilus_trader · error · anyhow::Error

Execution intent {} uses unsupported schema version {}

Error message

Execution intent {} uses unsupported schema version {}

What it means

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.

Source

Thrown at crates/adapters/blockchain/src/execution/client.rs:918

            fee,
            amount_in,
            min_amount_out: U256::ZERO,
            profiler_block: intent.created_block,
        })
    }

    async fn reconcile_unresolved_execution(&self) -> anyhow::Result<()> {
        let database = self.cache.database.clone().ok_or_else(|| {
            anyhow::anyhow!("No durable store configured for execution reconciliation")
        })?;
        let wallet_address = self.wallet_address.to_string();
        let Some(intent) = database
            .get_active_execution_intent(self.chain.chain_id, &wallet_address)
            .await?
        else {
            return Ok(());
        };
        anyhow::ensure!(
            intent.schema_version == crate::execution::transaction::EXECUTION_SCHEMA_VERSION,
            "Execution intent {} uses unsupported schema version {}",
            intent.id,
            intent.schema_version
        );

        if matches!(intent.status.as_str(), "prepared" | "signed") {
            database
                .mark_execution_intent_recoverable(intent.id)
                .await?;
            release_preparing_slot(&self.in_flight);
            return Ok(());
        }

        let purpose = TransactionPurpose::parse(&intent.purpose).ok_or_else(|| {
            anyhow::anyhow!(
                "Execution intent {} has unknown purpose {}",
                intent.id,

View on GitHub (pinned to 2114cf6f76)

Solutions

1. Check the stored row: SELECT id, schema_version, status, active FROM execution_intent WHERE chain_id = <chain> AND wallet_address = '<0x...>' AND active;
2. 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
3. Run any provided schema migration for the execution tables before reconnecting after an upgrade
4. For dev/test stores, point the client at a fresh postgres_cache_database_config instead of a store carrying foreign-version rows

Example fix

-- before: stale row blocks startup
SELECT id, schema_version FROM execution_intent WHERE active;
-- id=42, schema_version=1

-- after: archive the incompatible intent after verifying no funds are at risk
UPDATE execution_intent SET active = FALSE WHERE id = 42 AND schema_version <> 2;

-- Run before starting the trader, against the configured Postgres store
SELECT id, schema_version, status
FROM execution_intent
WHERE chain_id = :chain_id
  AND wallet_address = :wallet
  AND active
  AND schema_version <> 2;  -- current EXECUTION_SCHEMA_VERSION
-- Any row here means connect() will fail with the schema-version error.

try:
    client.connect()
except Exception as e:
    if 'unsupported schema version' in str(e):
        # halt: reconcile or archive the stale intent row before retrying
        raise RuntimeError(f'Stale execution intent schema: {e}')
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Execution schema version {} is newer than supported version
• Execution intent {} has unknown purpose {}
• Active execution intent {} has no nonce
• Failed to persist transaction {tx_hash}: {e}; the in-flight
• Failed to persist broadcast attempt for transaction {tx_hash

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