nautechsystems/nautilus_trader · error

Order amount overflow scaling quantity to raw token units

Error message

Order amount overflow scaling quantity to raw token units

What it means

After scaling an order quantity up to raw token units, the client multiplies the raw U256 value by 10^(decimals - raw_precision). This error is thrown when that multiplication overflows U256, i.e. the quantity is too large to express in base token units.

Solutions

  1. Reduce the order quantity to a value representable in raw token units
  2. Verify token decimals against the on-chain contract and correct the instrument config
  3. Add a pre-trade sanity check that quantity scaled fits within U256 and reject oversized orders before submission

Example fix

// before
raw.checked_mul(scale).ok_or_else(|| anyhow::anyhow!("Order amount overflow scaling quantity to raw token units"))
// after
let max_raw = U256::MAX / scale;
if raw > max_raw { anyhow::bail!("quantity {} exceeds raw token capacity", quantity); }
raw.checked_mul(scale).ok_or_else(|| anyhow::anyhow!("Order amount overflow scaling quantity to raw token units"))
Defensive patterns

Strategy: validation

Validate before calling

fn assert_order_size(quantity_raw: U256, scale: U256) -> Result<(), String> {
    if quantity_raw > U256::MAX / scale { Err("order quantity exceeds raw token capacity".into()) } else { Ok(()) }
}

Try / catch

match client.submit_order(...) {
    Err(e) if e.to_string().contains("Order amount overflow scaling quantity") => { /* halve size / re-check decimals */ }
    other => other?,
}

Prevention

When it happens

Trigger: Submitting an order whose quantity, once scaled by the token decimal delta, exceeds U256::MAX — e.g. a quantity at fixed precision near 2^256/10^k with decimals > raw_precision.

Common situations: Order size typo (e.g. entering 1,000,000,000 instead of 1.0); wrongly configured token decimals inflating the scale factor; trading a meme token with huge supply and large configured decimals.

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

Appendix: source

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

/// 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,
    base: Address,
    quote: Address,

View on GitHub (pinned to 18893faf8b)