nautechsystems/nautilus_trader · error

commission calculation overflow

Error message

commission calculation overflow

What it means

While computing commission as notional * rate in Decimal space, the checked multiplication overflowed, meaning the operands are too large for the Decimal representation. The library bails instead of producing a silently wrong commission.

Source

Thrown at crates/model/src/accounts/base.rs:409

        use_quote_for_inverse: Option<bool>,
    ) -> anyhow::Result<Money> {
        anyhow::ensure!(
            liquidity_side != LiquiditySide::NoLiquiditySide,
            "Invalid `LiquiditySide`: {liquidity_side}"
        );
        let notional =
            instrument.try_calculate_notional_value(last_qty, last_px, use_quote_for_inverse)?;
        let rate = match liquidity_side {
            LiquiditySide::Maker => instrument.maker_fee(),
            LiquiditySide::Taker => instrument.taker_fee(),
            LiquiditySide::NoLiquiditySide => {
                anyhow::bail!("Invalid `LiquiditySide`: {liquidity_side}")
            }
        };
        let commission = notional
            .as_decimal()
            .checked_mul(rate)
            .ok_or_else(|| anyhow::anyhow!("commission calculation overflow"))?;

        Ok(Money::from_decimal(commission, notional.currency)?)
    }
}

/// Updates the locked balance for the given instrument and currency, then recalculates the
/// account balance for that currency from all per-(instrument, currency) locks.
///
/// The reservation is recorded without a balance when the currency has no observed balance yet,
/// so a later balance report derives from it.
///
/// # Errors
///
/// Returns an error if `locked` is negative, its precision differs from the balance precision,
/// or the reservations cannot produce a valid balance. Balances and reservations are left
/// unchanged when an error is returned.
pub(crate) fn update_balance_locked(
    balances: &mut IndexMap<Currency, AccountBalance>,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Verify the commission rate is a fraction (e.g. 0.0002) not a percentage
2. Check that instrument price/quantity used for the notional are correct and within exchange norms
3. Scale down or validate inputs before calling calculate_commission

Example fix

// before
rate = Decimal("25")  # percent mistaken as fraction
// after
rate = Decimal("0.0025")

notional = qty.as_decimal() * px.as_decimal()
if notional * rate > Decimal('1e30'):
    raise ValueError('commission operands out of plausible range')

try:
    commission = account.calculate_commission(instrument, qty, px, side, None)
except Exception as e:
    log.error(f"commission overflow: {e}")

When it happens

Trigger: Calling base_calculate_commission with a notional value and commission rate whose product exceeds Decimal bounds — pathological prices/quantities or a wildly wrong rate.

Common situations: Misconfigured commission rate (e.g. percentage passed as 25 instead of 0.0025) combined with large notional, or corrupted price/quantity data from an adapter.

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

• WETH balance overflow for included transaction {tx_hash} at
• DurationNanos overflow in from_micros
• {e}
• Estimated gas {estimate} with {gas_buffer_bps} bps buffer ({
• DateTime timestamp out of range for UnixNanos: {nanos}

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