nautechsystems/nautilus_trader · error

Order amount scaling overflow

Error message

Order amount scaling overflow

What it means

When converting an order Quantity to raw token units, the client raises 10^(decimals - raw_precision) and multiplies the fixed-precision raw value. This error is thrown when the scaling power itself (10^exponent) overflows U256, meaning the decimal delta between the order precision and the token decimals is too large to represent.

Solutions

  1. Verify the token's decimals value matches the on-chain contract (call decimals() on the token) and fix the instrument/provider config
  2. Ensure quantity.precision (or FIXED_PRECISION fallback) is set correctly for the instrument so decimals - raw_precision stays small
  3. Cap or sanitize decimals before calling the conversion; reject tokens with implausible decimals values upstream

Example fix

// before
let scale = U256::from(10u64).checked_pow(U256::from(decimals - raw_precision))?;
// after
let exponent = (decimals - raw_precision) as u32;
if exponent > 78 { anyhow::bail!("decimals delta {exponent} too large for U256 scaling"); }
let scale = U256::from(10u64).checked_pow(U256::from(exponent))?;
Defensive patterns

Strategy: validation

Validate before calling

fn assert_scalable(quantity_precision: u32, decimals: u32) -> Result<(), String> {
    let delta = decimals.abs_diff(quantity_precision.max(FIXED_PRECISION));
    if delta > 78 { Err(format!("decimals delta {delta} cannot be scaled in U256")) } else { Ok(()) }
}

Try / catch

match client.submit_order(...) {
    Err(e) if e.to_string().contains("Order amount scaling overflow") => { /* fix decimals config / reject order */ }
    other => other?,
}

Prevention

When it happens

Trigger: Calling the execution client to submit an order whose instrument quantity precision differs from the token's decimals by an exponent so large that 10^(decimals - raw_precision) exceeds U256::MAX (e.g. absurd decimals values or a token with astronomically many decimals).

Common situations: Misconfigured instrument definitions where token decimals were read from the wrong contract or hardcoded incorrectly; a corrupted/malicious token metadata feed reporting decimals in the hundreds; copy-paste decimals from a different chain's token.

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

Appendix: source

Thrown at crates/adapters/blockchain/src/execution/client.rs:5211

}

/// Converts a base-denominated order quantity into raw token units with exact integer
/// scaling by the base token decimals.
///
/// `Quantity::raw` is scaled to the greater of its declared precision and `FIXED_PRECISION`;
/// token amounts are scaled to the token's decimals. Quantities not exactly representable in
/// token units are rejected rather than rounded.
fn quantity_to_raw_amount(quantity: Quantity, decimals: u8) -> anyhow::Result<U256> {
    if quantity.is_zero() {
        anyhow::bail!("Order quantity must be positive");
    }

    let raw = U256::from(quantity.raw);
    let raw_precision = quantity.precision.max(FIXED_PRECISION);
    if decimals >= raw_precision {
        let scale = U256::from(10u64)
            .checked_pow(U256::from(decimals - raw_precision))
            .ok_or_else(|| anyhow::anyhow!("Order amount scaling overflow"))?;
        raw.checked_mul(scale).ok_or_else(|| {
            anyhow::anyhow!("Order amount overflow scaling quantity to raw token units")
        })
    } else {
        let divisor = U256::from(10u64)
            .checked_pow(U256::from(raw_precision - decimals))
            .ok_or_else(|| anyhow::anyhow!("Order amount scaling overflow"))?;
        if !(raw % divisor).is_zero() {
            anyhow::bail!(
                "Order quantity {quantity} is not exactly representable in {decimals} base token decimals"
            );
        }
        Ok(raw / divisor)
    }
}

fn swap_token_pair(
    side: OrderSide,

View on GitHub (pinned to 18893faf8b)