nautechsystems/nautilus_trader · critical

Overflow in Quantity::from_mantissa_exponent

Error message

Overflow in Quantity::from_mantissa_exponent

What it means

Quantity::from_mantissa_exponent scales the mantissa by 10^(exponent - precision) (or divides) into an i128 via mantissa_exponent_to_fixed_i128; when the scaled value overflows i128 the helper returns None and this expect panics. It exists to prevent silently wrapping quantity values.

Source

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

    /// Creates a new [`Quantity`] from a mantissa/exponent pair using pure integer arithmetic.
    ///
    /// The value is `mantissa * 10^exponent`. This avoids all floating-point and Decimal
    /// 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`].

View on GitHub (pinned to 18893faf8b)

Solutions

1. Correct the mantissa/exponent to the instrument's actual size/precision so the scaled value fits in i128.
2. Pre-validate: confirm |mantissa| * 10^(exponent - precision) < 2^127 before calling.
3. Normalize data at ingestion: convert to Decimal first, range-check, then construct Quantity.
4. Reject or clamp quantities exceeding the instrument's max quantity in your data pipeline.

Example fix

// before
let qty = Quantity::from_mantissa_exponent(10_000_000_000_i64, 25, 8); // panics: i128 overflow
// after
let qty = Quantity::from_mantissa_exponent(1_234_567_i64, -6, 8); // 1.234567 at precision 8

// Rust
fn can_build_quantity(mantissa: i64, exponent: i8, precision: u8) -> bool {
    let diff = i32::from(exponent) - i32::from(precision);
    mantissa >= 0
        && (mantissa.checked_ilog10().map(|d| d as i32).unwrap_or(0) + diff) <= 38 // i128 log10 bound
}

fn quantity_fits(value: Decimal, precision: u8) -> bool {
    let scaled = value * Decimal::from(10_u32.pow(u32::from(precision)));
    scaled >= Decimal::ZERO && scaled <= Decimal::from(i128::MAX)
}

When it happens

Trigger: Quantity::from_mantissa_exponent(mantissa, exponent, precision) where scaling the mantissa to the target precision exceeds i128 — huge mantissa with large positive exponent, or an enormous precision gap requiring multiplication by 10^n beyond i128.

Common situations: Bad instrument definitions from venue configs (absurd step-size exponents); parsing CSV/JSON quantity fields with wrong units (e.g. wei-scale integers treated as whole coins); copy-pasted exponent conventions between venues.

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
• Raw value exceeds QuantityRaw range in Quantity::from_mantis
• 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/84b5d45ac4963854. Report an issue: GitHub.