nautechsystems/nautilus_trader · error

Python on_pool_liquidity_update failed: {e}

Error message

Python on_pool_liquidity_update failed: {e}

What it means

Raised by `DataActor::on_pool_liquidity_update` (crates/common/src/python/actor.rs:1187) when dispatching a `PoolLiquidityUpdate` event to the Python actor fails. The dispatch invokes the Python instance's `on_pool_liquidity_update` method via pyo3's `call_method1`, so a Python exception in the handler, a missing method, or a conversion failure of the event to a Python object becomes `Python on_pool_liquidity_update failed: {e}`. It propagates Python-side handler failures into the Rust actor's error path.

Source

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

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

    #[cfg(feature = "defi")]
    fn on_pool(&mut self, pool: &Pool) -> anyhow::Result<()> {
        self.dispatch_on_pool(pool.clone())
            .map_err(|e| anyhow::anyhow!("Python on_pool failed: {e}"))
    }

    #[cfg(feature = "defi")]
    fn on_pool_swap(&mut self, swap: &PoolSwap) -> anyhow::Result<()> {
        self.dispatch_on_pool_swap(swap.clone())
            .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()

View on GitHub (pinned to 18893faf8b)

Solutions

1. Read the wrapped `{e}` cause for the original Python exception/traceback and fix the code inside your `on_pool_liquidity_update` handler.
2. Ensure the Python actor class implements `on_pool_liquidity_update(self, update)` if it subscribes to pool liquidity updates.
3. Guard arithmetic in the handler against zero/None values (e.g. liquidity, sqrt_price_x96) before computing.
4. Re-verify handler field access against the PoolLiquidityUpdate definition for your installed nautilus version.

Example fix

# before: ZeroDivisionError on empty pool liquidity
def on_pool_liquidity_update(self, update):
    price = update.sqrt_price_x96 ** 2 / update.liquidity

# after
def on_pool_liquidity_update(self, update):
    if not update.liquidity:
        return
    price = update.sqrt_price_x96 ** 2 / update.liquidity

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

def has_liquidity_update_handler(obj):
    return callable(getattr(obj, 'on_pool_liquidity_update', None))

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

When it happens

Trigger: Fires when a `PoolLiquidityUpdate` (mint/burn liquidity event) arrives for a defi-enabled actor and the Python callback raises, the Python object lacks a callable `on_pool_liquidity_update`, or `update.into_py_any(py)` conversion fails.

Common situations: Handlers doing liquidity math (sqrt price, tick range, share valuation) hitting ZeroDivisionError or OverflowError; subscribing to pool liquidity updates without implementing the handler; version drift where the event field names changed; exceptions from external calls (web3 queries) inside the handler.

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

• Python on_pool_swap failed: {e}
• Python on_pool_fee_collect failed: {e}
• Python on_pool_flash failed: {e}
• Failed to convert historical data to Python: unsupported typ
• Failed to convert instrument to Python: {e}

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