What causes "Slippage {actual_slippage} bps exceeds tolerance {max_slippage_bps} bps" in nautechsystems/nautilus_trader?

Increase `max_slippage_bps` to an acceptable value (remember the unit is basis points: 100 bps = 1%).

nautechsystems/nautilus_trader · warning · anyhow::Error

Slippage {actual_slippage} bps exceeds tolerance {max_slippa

Error message

Slippage {actual_slippage} bps exceeds tolerance {max_slippage_bps} bps

What it means

`validate_slippage_tolerance` computes the quote's actual slippage in basis points and compares it to the caller-supplied `max_slippage_bps`. If actual slippage strictly exceeds the tolerance, it bails with this message naming both values. This is an intentional domain rejection, not an internal bug: the trade simply moves the price (including fees) beyond what the caller will accept.

Source

Thrown at crates/model/src/defi/pool_analysis/quote.rs:247

    /// # Returns
    /// Total slippage in basis points (10000 = 100%)
    ///
    /// # Errors
    /// Returns error if price calculations fail
    pub fn get_slippage_bps(&mut self) -> anyhow::Result<u32> {
        match self.check_if_trade_info_initialized() {
            Ok(trade_info) => trade_info.get_slippage_bps(),
            Err(e) => anyhow::bail!("Failed to calculate slippage: {e}"),
        }
    }

    /// # Errors
    ///
    /// Returns an error if the actual slippage exceeds the maximum slippage tolerance.
    pub fn validate_slippage_tolerance(&mut self, max_slippage_bps: u32) -> anyhow::Result<()> {
        let actual_slippage = self.get_slippage_bps()?;
        if actual_slippage > max_slippage_bps {
            anyhow::bail!(
                "Slippage {actual_slippage} bps exceeds tolerance {max_slippage_bps} bps"
            );
        }
        Ok(())
    }

    /// Validates that the quote satisfied an exact output request.
    ///
    /// # Errors
    /// Returns error if the actual output is less than the requested amount.
    pub fn validate_exact_output(&self, amount_out_requested: U256) -> anyhow::Result<()> {
        let actual_out = self.get_output_amount();
        if actual_out < amount_out_requested {
            anyhow::bail!(
                "Insufficient liquidity: requested {amount_out_requested}, available {actual_out}"
            );
        }
        Ok(())

View on GitHub (pinned to 18893faf8b)

Solutions

Increase `max_slippage_bps` to an acceptable value (remember the unit is basis points: 100 bps = 1%).
Reduce the trade size or split it into smaller swaps to lower price impact.
Verify slippage is expressed in bps, not percent, before comparing.
Route through a deeper pool or different pool to reduce impact, then re-validate.

Example fix

// before
// 5% intended, but passed as percent-like value
quote.validate_slippage_tolerance(5)?;
// after
// 5% expressed in basis points
quote.validate_slippage_tolerance(500)?;

Defensive patterns

Strategy: try-catch

Validate before calling

let slippage = quote.get_slippage_bps()?;
if slippage > max_slippage_bps {
    // skip trade or renegotiate size before calling validate_slippage_tolerance
}

Try / catch

if let Err(e) = quote.validate_slippage_tolerance(max_slippage_bps) {
    if e.to_string().contains("exceeds tolerance") {
        // reduce size, widen tolerance, or skip the trade
    } else {
        return Err(e); // computation failure, not a tolerance rejection
    }
}

Prevention

Express all tolerances in basis points consistently (100 bps = 1%).
Size trades against pool depth before validating slippage.
Set tolerance from config with unit documentation and sane defaults.
Re-validate slippage shortly before execution; pool state changes shift impact.

When it happens

Trigger: Calling `validate_slippage_tolerance(max_slippage_bps)` where `get_slippage_bps()` returns a value greater than `max_slippage_bps`; also triggered indirectly when the trade-info path fails, since slippage computation errors propagate through this method first.

Common situations: Large trade sizes relative to pool liquidity; low-liquidity pools; setting tolerance in the wrong unit (10 meaning 10% instead of 10 bps); volatile pairs at times of high price impact.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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