What causes "Simulation module failure requires exchange reset: {error}" in nautechsystems/nautilus_trader?

Reset the exchange (and engine) after fixing the module fault before continuing processing

nautechsystems/nautilus_trader · critical

Simulation module failure requires exchange reset: {error}

Error message

Simulation module failure requires exchange reset: {error}

What it means

A simulation module (e.g. a funding or fee module) attached to the exchange reported an error during processing; the exchange marks itself with module_error and every subsequent check aborts, requiring the exchange to be reset before processing can continue. This prevents operating on an exchange whose module state is inconsistent.

Source

Thrown at crates/backtest/src/exchange.rs:331

    /// Sets the latency model for the exchange.
    pub fn set_latency_model(&mut self, latency_model: LatencyModelHandle) {
        self.latency_model = Some(latency_model);
    }

    #[must_use]
    pub(crate) const fn has_modules(&self) -> bool {
        !self.modules.is_empty()
    }

    #[must_use]
    pub(crate) const fn liquidation_enabled(&self) -> bool {
        self.liquidation_enabled
    }

    pub(crate) fn check_module_error(&self) -> anyhow::Result<()> {
        if let Some(error) = &self.module_error {
            anyhow::bail!("Simulation module failure requires exchange reset: {error}");
        }
        Ok(())
    }

    #[must_use]
    pub(crate) const fn has_module_error(&self) -> bool {
        self.module_error.is_some()
    }

    fn store_module_error(
        &mut self,
        module_index: usize,
        method: &str,
        error: &anyhow::Error,
    ) -> anyhow::Error {
        let error = format!("Simulation module {module_index} {method} failed: {error:#}");
        self.module_error = Some(error.clone());
        anyhow::anyhow!(error)

View on GitHub (pinned to 18893faf8b)

Solutions

Reset the exchange (and engine) after fixing the module fault before continuing processing
Inspect the embedded module error message to find which simulation module failed and why
Validate module inputs (funding rates, fee models) that could raise mid-processing

Example fix

// before
exchange.process(...)?; // fails: module error latched
// after
exchange.reset()?; // clears module_error after fixing the module fault
exchange.process(...)?;

Defensive patterns

Strategy: try-catch

Try / catch

if let Err(e) = exchange.check_module_error() {
    if e.to_string().starts_with("Simulation module failure requires exchange reset") {
        eprintln!("module fault: {e}; fixing and resetting exchange");
        exchange.reset()?;
    }
}

Prevention

Always reset() the exchange/engine after a module fault before further processing
Read the embedded error to identify which simulation module failed
Validate module inputs (funding rates, fee models) that can raise mid-simulation

When it happens

Trigger: Any module hook raising during pre_process_modules, process_funding_settlement, process_modules, or reset; then a later check_module_error() call surfaces it.

Common situations: Funding rate calculation failure mid-backtest; module hitting invalid market state; reusing an exchange after a module fault without resetting.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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