nautechsystems/nautilus_trader · critical

Raw value exceeds QuantityRaw range in Quantity::from_mantis

Error message

Raw value exceeds QuantityRaw range in Quantity::from_mantissa_exponent

What it means

After the i128 conversion succeeds, from_mantissa_exponent narrows the i128 raw into QuantityRaw via try_into with expect; if the value exceeds QuantityRaw's range (negative or above QUANTITY_RAW_MAX), it panics. The subsequent assert documents the QUANTITY_RAW_MAX bound that must hold.

Source

Thrown at crates/model/src/types/quantity.rs:537

    /// operations, making it ideal for exchange data that arrives as mantissa/exponent pairs.
    ///
    /// # Panics
    ///
    /// Panics if the resulting raw value exceeds [`QUANTITY_RAW_MAX`].
    #[must_use]
    pub fn from_mantissa_exponent(mantissa: u64, exponent: i8, precision: u8) -> Self {
        check_fixed_precision(precision).expect_display(FAILED);

        if mantissa == 0 {
            return Self { raw: 0, precision };
        }

        let raw_i128 = mantissa_exponent_to_fixed_i128(i128::from(mantissa), exponent, precision)
            .expect("Overflow in Quantity::from_mantissa_exponent");

        let raw: QuantityRaw = raw_i128
            .try_into()
            .expect("Raw value exceeds QuantityRaw range in Quantity::from_mantissa_exponent");
        assert!(
            raw <= QUANTITY_RAW_MAX,
            "`raw` value {raw} exceeded QUANTITY_RAW_MAX={QUANTITY_RAW_MAX} for Quantity"
        );

        Self { raw, precision }
    }

    /// Checked variant of [`Quantity::from_mantissa_exponent`].
    ///
    /// # Errors
    ///
    /// Returns an error if the precision is invalid or the resulting raw value
    /// exceeds [`QUANTITY_RAW_MAX`].
    pub fn from_mantissa_exponent_checked(
        mantissa: u64,
        exponent: i8,
        precision: u8,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Ensure the mantissa is non-negative and the scaled value <= QUANTITY_RAW_MAX before calling.
2. Clamp or reject quantities exceeding the instrument's max quantity during ingestion.
3. Compute in Decimal first, validate against QUANTITY_RAW_MAX, then construct.
4. Use the high-precision build (wider QuantityRaw) if legitimate quantity ranges need it.

Example fix

// before
let qty = Quantity::from_mantissa_exponent(-5_i64, 0, 8); // panics: negative raw into unsigned QuantityRaw
// after
let qty = Quantity::from_mantissa_exponent(5_i64, 0, 8); // 5.00000000

// Rust
fn quantity_raw_fits(mantissa: i64, exponent: i8, precision: u8) -> bool {
    mantissa >= 0 && mantissa_exponent_to_fixed_i128(i128::from(mantissa), exponent, precision)
        .map(|raw| raw >= 0 && raw <= i128::from(QUANTITY_RAW_MAX))
        .unwrap_or(false)
}

fn to_quantity_raw(raw: i128) -> Option<QuantityRaw> {
    QuantityRaw::try_from(raw).ok().filter(|r| *r <= QUANTITY_RAW_MAX)
}

When it happens

Trigger: Quantity::from_mantissa_exponent whose scaled raw fits i128 but exceeds QUANTITY_RAW_MAX, or is negative (negative mantissa), which try_into to the unsigned QuantityRaw rejects.

Common situations: Passing negative mantissas (signed deltas) where only unsigned quantities are allowed; high-precision builds with quantities beyond the raw bound; importing historical data with sentinel/placeholder max 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

• Whole raw quantity must fit in Decimal
• Overflow in Quantity::from_mantissa_exponent
• Overflow occurred when adding `Quantity`
• Liquidity addition overflow: x={current}, y={y}, delta={delt
• mul_div overflow

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