nautechsystems/nautilus_trader · info

Fractional raw quantity must fit in Decimal

Error message

Fractional raw quantity must fit in Decimal

What it means

The fractional component of raw_as_decimal (raw % FIXED_SCALAR_RAW) is narrowed to i128 via try_from with expect. Because the remainder is strictly less than FIXED_SCALAR_RAW (10^FIXED_PRECISION, a small constant), this panic is only reachable if FIXED_SCALAR_RAW itself exceeded i128 range, i.e. an extreme fixed-precision configuration; it is a defensive invariant check rather than a condition callers can normally cause.

Source

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

        #[allow(
            clippy::unnecessary_cast,
            clippy::cast_lossless,
            reason = "cast is real when QuantityRaw is u64, no-op when u128"
        )]
        scaled_raw_to_decimal(rescaled_raw as i128, self.precision)
    }

    /// Returns a raw fixed-point quantity as a `Decimal`.
    #[must_use]
    #[allow(
        clippy::unnecessary_fallible_conversions,
        reason = "try_from is infallible when QuantityRaw is u64, fallible when u128"
    )]
    pub(crate) fn raw_as_decimal(raw: QuantityRaw) -> Decimal {
        let whole =
            i128::try_from(raw / FIXED_SCALAR_RAW).expect("Whole raw quantity must fit in Decimal");
        let fractional = i128::try_from(raw % FIXED_SCALAR_RAW)
            .expect("Fractional raw quantity must fit in Decimal");

        Decimal::from(whole) + Decimal::from_i128_with_scale(fractional, u32::from(FIXED_PRECISION))
    }

    /// Returns a formatted string representation of this instance.
    #[must_use]
    pub fn to_formatted_string(&self) -> String {
        format!("{self}").separate_with_underscores()
    }

    /// Creates a new [`Quantity`] from a `Decimal` value with specified precision.
    ///
    /// Uses pure integer arithmetic on the Decimal's mantissa and scale for fast conversion.
    /// The value is rounded to the specified precision using banker's rounding (round half to even).
    ///
    /// # Errors
    ///
    /// Returns an error if:

View on GitHub (pinned to 18893faf8b)

Solutions

1. Nothing actionable for callers; if triggered, it indicates a broken build configuration of FIXED_PRECISION.
2. Keep FIXED_PRECISION at supported values (e.g. 9/16/18) so FIXED_SCALAR_RAW stays far below i128 range.
3. Report to maintainers if this panic is observed — it signals an internal invariant violation.

When it happens

Trigger: Practically unreachable: raw_as_decimal would only panic here if the build's FIXED_PRECISION made FIXED_SCALAR_RAW larger than i128::MAX, since raw % FIXED_SCALAR_RAW is always < FIXED_SCALAR_RAW.

Common situations: Only conceivable in custom high-precision builds with pathological FIXED_PRECISION values; users of default builds will never encounter it.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Whole raw quantity must fit in Decimal
• Close command should not be drained
• Flush command should not be drained
• {e}
• Order invariant violated: first event must be OrderInitializ

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