nautechsystems/nautilus_trader · error

Replacement scan manifest identity changed

Error message

Replacement scan manifest identity changed

What it means

load_execution_replacement_cursor joins the stored replacement scan row with its verified finalized header and compares the stored manifest_digest against the caller-supplied manifest_digest. If they differ, the persisted scan cursor belongs to a different verification manifest than the current one, so the code refuses to return it.

Solutions

  1. Regenerate the replacement scan under the current manifest so the stored digest matches
  2. Pass the manifest_digest that was used when the scan was recorded (check execution_replacement_scan.manifest_digest)
  3. Confirm the (intent_id, chain_id, wallet_address, nonce) tuple identifies the intended scan row
  4. Clear stale scan rows after a manifest change and rescan

Example fix

// before
let cursor = db.load_execution_replacement_cursor(intent_id, chain, wallet, nonce, &new_manifest_digest).await?;
// after
let stored: Option<String> = sqlx::query_scalar(
    "SELECT manifest_digest FROM execution_replacement_scan WHERE intent_id=$1 AND nonce=$2",
).bind(intent_id).bind(nonce as i64).fetch_optional(&db.pool).await?;
let cursor = db.load_execution_replacement_cursor(intent_id, chain, wallet, nonce,
    stored.as_deref().expect("scan must exist before loading cursor")).await?;
Defensive patterns

Strategy: validation

Validate before calling

let stored: Option<String> = sqlx::query_scalar(
    "SELECT manifest_digest FROM execution_replacement_scan WHERE intent_id=$1 AND chain_id=$2 AND wallet_address=$3 AND nonce=$4",
).bind(intent_id).bind(chain_id).bind(wallet).bind(nonce as i64)
.fetch_optional(&pool).await?;
if stored.as_deref() != Some(current_manifest_digest) {
    // rescan under the current manifest instead of loading the stale cursor
}

Type guard

fn digest_matches(stored: &Option<String>, expected: &str) -> bool {
    stored.as_deref() == Some(expected)
}

Try / catch

match db.load_execution_replacement_cursor(intent_id, chain, wallet, nonce, digest).await {
    Err(e) if e.to_string().contains("manifest identity changed") => {
        // invalidate stored scan and re-run record_execution_replacement_scan
    }
    other => other,
}

Prevention

When it happens

Trigger: Calling load_execution_replacement_cursor with a manifest_digest that differs from the digest stored on the execution_replacement_scan row for that (intent_id, chain_id, wallet_address, nonce).

Common situations: The verification manifest was regenerated (code/schema change) after the scan was recorded; pointing at the wrong wallet/nonce so the digest lookup matches a different scan; upgrading the binary between recording and loading the cursor.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors


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

Appendix: source

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

             AND h.wallet_address = s.wallet_address
             AND h.number = s.finalized_cursor_number
             AND h.hash = s.finalized_cursor_hash
            WHERE s.intent_id = $1
              AND s.chain_id = $2
              AND s.wallet_address = $3
              AND s.nonce = $4
            ",
        )
        .bind(intent_id)
        .bind(chain_id)
        .bind(wallet_address)
        .bind(nonce)
        .fetch_optional(&self.pool)
        .await
        .context("failed to load replacement scan cursor")?;
        row.map(
            |(number, hash, parent_hash, timestamp, base_fee, stored_digest)| {
                anyhow::ensure!(
                    stored_digest == manifest_digest,
                    "Replacement scan manifest identity changed"
                );
                Ok(ExecutionVerifiedHeader {
                    number: u64::try_from(number)
                        .context("Replacement scan cursor number is negative")?,
                    hash,
                    parent_hash,
                    timestamp: u64::try_from(timestamp)
                        .context("Replacement scan cursor timestamp is negative")?,
                    base_fee_per_gas: base_fee
                        .map(|value| {
                            value.parse::<u128>().map_err(|_| {
                                anyhow::anyhow!("Replacement scan cursor base fee is invalid")
                            })
                        })
                        .transpose()?,
                })

View on GitHub (pinned to 18893faf8b)