nautechsystems/nautilus_trader · error

quantity for {currency} exceeds signed raw bounds

Error message

quantity for {currency} exceeds signed raw bounds

What it means

The quantity's raw fixed-precision value is stored as u64 but Money raw values are i128-backed. Converting u128 -> i128 fails if the raw value exceeds i128::MAX; this error signals the quantity magnitude cannot fit the signed representation required for Money arithmetic.

Source

Thrown at crates/portfolio/src/manager.rs:1422

                },
            ),
        }
    }
}

#[allow(
    clippy::useless_conversion,
    reason = "the raw width differs when high-precision is disabled"
)]
fn wallet_money_from_quantity(quantity: Quantity, currency: Currency) -> anyhow::Result<Money> {
    anyhow::ensure!(!quantity.is_undefined(), "quantity was undefined");
    Quantity::from_raw_checked(quantity.raw, quantity.precision)?;
    check_fixed_raw_u128(u128::from(quantity.raw), quantity.precision)?;

    let source_precision = quantity.precision.max(FIXED_PRECISION);
    let target_precision = currency.precision.max(FIXED_PRECISION);
    let raw = i128::try_from(u128::from(quantity.raw))
        .map_err(|_| anyhow::anyhow!("quantity for {currency} exceeds signed raw bounds"))?;
    let raw = match source_precision.cmp(&target_precision) {
        Ordering::Less => {
            let scale = 10_i128.pow(u32::from(target_precision - source_precision));
            raw.checked_mul(scale).ok_or_else(|| {
                anyhow::anyhow!("quantity for {currency} overflowed while increasing raw scale")
            })?
        }
        Ordering::Greater => {
            let scale = 10_i128.pow(u32::from(source_precision - target_precision));
            anyhow::ensure!(
                raw % scale == 0,
                "quantity for {currency} loses precision when decreasing raw scale"
            );
            raw / scale
        }
        Ordering::Equal => raw,
    };
    check_fixed_raw_i128(raw, currency.precision)?;

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Check upstream arithmetic for overflow that produced the huge raw value
  2. Use a smaller quantity / correct precision consistent with the instrument
  3. Add a magnitude check before calling update_balance_locked_wallet
  4. Verify Quantity precision matches the currency/instrument precision

Example fix

// before
manager.update_balance_locked_wallet(&instrument.id(), asset, huge_quantity)?;
// after
let max_raw = i128::from(u64::MAX); // u64 raw always fits i128; guard anyway for high-precision paths
anyhow::ensure!(u128::from(huge_quantity.raw) <= i128::MAX as u128, "quantity too large");
manager.update_balance_locked_wallet(&instrument.id(), asset, huge_quantity)?;
Defensive patterns

Strategy: validation

Validate before calling

fn fits_signed_raw(q: &Quantity) -> bool {
    u128::from(q.raw) <= i128::MAX as u128
}
anyhow::ensure!(fits_signed_raw(&quantity), "quantity too large for Money conversion");

Type guard

fn fits_signed_raw(q: &Quantity) -> bool { u128::from(q.raw) <= i128::MAX as u128 }

Try / catch

manager.update_balance_locked_wallet(&id, currency, quantity)
    .map_err(|e| { error!("wallet update failed: {e}"); e })?;

Prevention

When it happens

Trigger: Passing a Quantity with an extremely large raw value (near u64::MAX at its precision) into wallet_money_from_quantity via update_balance_locked_wallet.

Common situations: Corrupted or overflowed quantity arithmetic upstream; wrong precision making raw values enormous; synthetic/test data with sentinel-like huge values.

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/39f2fc373cb9b1a8. Report an issue: GitHub.