nautechsystems/nautilus_trader · error

Order quantity must be positive

Error message

Order quantity must be positive

What it means

quantity_to_raw_amount converts an order Quantity into a raw U256 token amount scaled to the token's decimals. A zero quantity cannot represent a valid order, so the conversion bails immediately with this error.

Solutions

  1. Validate the order quantity is strictly positive before constructing/submitting the order
  2. Fix the sizing calculation that produced zero (fees, rounding, or floor-to-zero)
  3. Check upstream market data / balance inputs that led to a zero size
  4. Skip zero-sized orders rather than submitting them

Example fix

// before: submitting whatever quantity was computed
let order = Order::new(instrument, quantity);
// after: guard zero size upstream
if quantity.is_zero() {
    return Ok(None); // skip order
}
let order = Order::new(instrument, quantity);
Defensive patterns

Strategy: validation

Validate before calling

anyhow::ensure!(!quantity.is_zero(), "order quantity must be positive, got {:?}", quantity);

Type guard

fn is_valid_order_quantity(q: &Quantity) -> bool { !q.is_zero() }

Try / catch

match res {
    Err(e) if e.to_string().contains("quantity must be positive") => {
        log::warn!("skipping zero-sized order");
        Ok(None)
    }
    other => other?,
}

Prevention

When it happens

Trigger: Calling any order/swap path that converts an order Quantity (quantity_to_raw_amount) with quantity.is_zero() — e.g. an order built with size 0, a quantity computed as zero after fee/netting math, or an uninitialized default Quantity.

Common situations: Order sizing logic producing 0 after subtracting fees from a small balance; a market-data-driven quantity of 0 for a delisted/illiquid instrument; a bug where the quantity field was never populated before submission.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors


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

Appendix: source

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

            plan.token_in,
            balance.value,
            plan.amount_in
        );
    }
    decisions.push(verification_decision(&balance, Some(block), Some(block)));

    Ok(decisions)
}

/// 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"

View on GitHub (pinned to 18893faf8b)