nautechsystems/nautilus_trader · error

Execution intent uses unsupported schema version

Error message

Execution intent {} uses unsupported schema version {}

What it means

The persisted execution intent's schema_version does not match the EXECUTION_SCHEMA_VERSION compiled into this build. The client cannot safely interpret or replay intents written by an incompatible version, so reconciliation aborts.

Solutions

1. Drain or resolve the active execution intent with the software version that wrote it before upgrading
2. Migrate the persisted intent row to the current schema version using an upgrade/migration path
3. Roll back to the binary version matching the intent's schema_version to finish recovery
4. Start with a clean execution database only after verifying no in-flight funds depend on the old intent

let intent = database.get_active_execution_intent(chain_id, &wallet).await?;
if let Some(i) = &intent {
    if i.schema_version != EXECUTION_SCHEMA_VERSION {
        // resolve/migrate before connecting
    }
}

When it happens

Trigger: connect() -> reconcile_unresolved_execution() loads get_active_execution_intent() and its schema_version differs from crate::execution::transaction::EXECUTION_SCHEMA_VERSION.

Common situations: Upgrading/downgrading the software while an intent from the old version is still active in the database; database shared between deployments running different versions.

Related errors

• Execution schema version
• Execution verification schema version
• Cannot safely migrate
• Failed to install verification schema
• Failed to read execution schema version

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

Appendix: source

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

            .acquire_execution_payload_lease(self.payload_keys.as_deref().ok_or_else(|| {
                anyhow::anyhow!("Protected payload keys are required for execution recovery")
            })?)
            .await?;
        let wallet_address = self.wallet_address.to_string();
        anyhow::ensure!(
            !database
                .has_recoverable_signed_execution(self.chain.chain_id, &wallet_address)
                .await?,
            "A recoverable execution for wallet {} retains signed transaction bytes; refusing to reuse its nonce without explicit recovery",
            self.wallet_address
        );
        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 intent.status == "prepared" {
            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 18893faf8b)