nautechsystems/nautilus_trader · error

Python on_pool_flash failed: {e}

Error message

Python on_pool_flash failed: {e}

What it means

Raised by `DataActor::on_pool_flash` (crates/common/src/python/actor.rs:1199) when dispatching a `PoolFlash` (flash-loan) event to the Python actor's `on_pool_flash` callback fails. `dispatch_on_pool_flash` calls the Python method via pyo3 `call_method1`; a Python exception in the handler, a missing method, or conversion of the event via `into_py_any` failing is wrapped as `Python on_pool_flash failed: {e}`.

Source

Thrown at crates/common/src/python/actor.rs:1199

            .map_err(|e| anyhow::anyhow!("Python on_pool_swap failed: {e}"))
    }

    #[cfg(feature = "defi")]
    fn on_pool_liquidity_update(&mut self, update: &PoolLiquidityUpdate) -> anyhow::Result<()> {
        self.dispatch_on_pool_liquidity_update(update.clone())
            .map_err(|e| anyhow::anyhow!("Python on_pool_liquidity_update failed: {e}"))
    }

    #[cfg(feature = "defi")]
    fn on_pool_fee_collect(&mut self, collect: &PoolFeeCollect) -> anyhow::Result<()> {
        self.dispatch_on_pool_fee_collect(collect.clone())
            .map_err(|e| anyhow::anyhow!("Python on_pool_fee_collect failed: {e}"))
    }

    #[cfg(feature = "defi")]
    fn on_pool_flash(&mut self, flash: &PoolFlash) -> anyhow::Result<()> {
        self.dispatch_on_pool_flash(flash.clone())
            .map_err(|e| anyhow::anyhow!("Python on_pool_flash failed: {e}"))
    }

    fn on_historical_data(&mut self, data: &dyn Any) -> anyhow::Result<()> {
        Python::attach(|py| {
            let py_data: Py<PyAny> = if let Some(custom_data) = data.downcast_ref::<CustomData>() {
                Py::new(py, custom_data.clone())?.into_any()
            } else if let Some(custom_data) = data.downcast_ref::<Vec<CustomData>>() {
                custom_data.clone().into_py_any(py)?
            } else {
                anyhow::bail!("Failed to convert historical data to Python: unsupported type");
            };
            self.dispatch_on_historical_data(py_data)
                .map_err(|e| anyhow::anyhow!("Python on_historical_data failed: {e}"))
        })
    }

    fn on_historical_book_deltas(&mut self, deltas: &[OrderBookDelta]) -> anyhow::Result<()> {
        self.dispatch_on_historical_book_deltas(deltas.to_vec())

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Unwrap the `{e}` cause to see the original Python exception and fix the `on_pool_flash` handler code.
  2. Ensure the Python actor implements `on_pool_flash(self, flash)` when subscribing to flash events.
  3. Add validation of flash amounts/tokens in the handler and short-circuit on unexpected values.
  4. Check the PoolFlash type definition for your nautilus version and update handler field access after upgrades.

Example fix

# before
def on_pool_flash(self, flash):
    profit = self.value_received(flash) - self.value_owed(flash)
    self.submit_order(self.build_arb(profit))  # raises if profit < 0

# after
def on_pool_flash(self, flash):
    profit = self.value_received(flash) - self.value_owed(flash)
    if profit <= 0:
        self.log.info(f"No arb in flash event: {profit}")
        return
    self.submit_order(self.build_arb(profit))
Defensive patterns

Strategy: try-catch

Validate before calling

assert callable(getattr(actor, 'on_pool_flash', None)), "actor must implement on_pool_flash"

Type guard

def has_flash_handler(obj):
    return callable(getattr(obj, 'on_pool_flash', None))

Try / catch

try:
    actor.on_pool_flash(flash)
except Exception as e:
    log.error(f"on_pool_flash failed: {e}", exc_info=True)

Prevention

When it happens

Trigger: Occurs when a pool flash-loan event reaches a defi-enabled actor and the Python callback raises, the Python instance lacks a callable `on_pool_flash`, or `flash.into_py_any(py)` conversion errors.

Common situations: Flash-loan arbitrage handlers raising on unexpected amounts/tokens; missing handler on a class that subscribes to flash events; protocol-specific parsing bugs (e.g. Aave/Uniswap flash payloads); version drift in event schema.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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