nautechsystems/nautilus_trader · error · anyhow::Error

fill group average price is not representable

Error message

fill group average price is not representable

What it means

After computing the aggregate quantity and notional, the manager derives the average price as `notional.checked_div(quantity)` and throws this error if the division fails (overflow or a Decimal arithmetic edge). It means the fill group's average price cannot be represented in the internal fixed-precision Decimal. In practice this follows extreme notional/quantity magnitudes rather than normal trading values.

Source

Thrown at crates/live/src/execution/manager.rs:1336

                    })?;

                let notional = notional.checked_add(fill_notional).ok_or_else(|| {
                    anyhow::anyhow!("fill notional overflow while aggregating fill group")
                })?;

                Ok::<_, anyhow::Error>((quantity, notional))
            },
        )?;

        anyhow::ensure!(
            quantity > Decimal::ZERO,
            "fill group quantity is not positive"
        );

        let order_qty = Quantity::from_decimal_dp(quantity, instrument.size_precision())?;
        let avg_px = notional
            .checked_div(quantity)
            .ok_or_else(|| anyhow::anyhow!("fill group average price is not representable"))?;

        let ts_accepted = fills
            .iter()
            .map(|fill| fill.ts_event)
            .min()
            .expect("non-empty fill group");

        let ts_last = fills
            .iter()
            .map(|fill| fill.ts_event)
            .max()
            .expect("non-empty fill group");

        let ts_init = fills
            .iter()
            .map(|fill| fill.ts_init)
            .max()
            .expect("non-empty fill group");

View on GitHub (pinned to 18893faf8b)

Solutions

1. Check the group's total notional and quantity values — an extreme ratio indicates malformed fills
2. Fix adapter price/quantity scaling so per-fill values are within realistic instrument bounds
3. Validate fills before aggregation (reject fills whose qty*px is implausible for the instrument)
4. If legitimate, compute the average price incrementally with explicit precision handling and report the Decimal limitation upstream

fn average_price_representable(fills: &[Fill]) -> bool {
    fills.iter().try_fold((Decimal::ZERO, Decimal::ZERO), |(q, n), f| {
        let fq = f.last_qty.as_decimal();
        let fn_ = fq.checked_mul(f.last_px.as_decimal())?;
        Some((q.checked_add(fq)?, n.checked_add(fn_)?))
    })
    .and_then(|(q, n)| if q > Decimal::ZERO { n.checked_div(q) } else { None })
    .is_some()
}

fn avg_px_computable(fills: &[Fill]) -> bool {
    let qty: Decimal = fills.iter().map(|f| f.last_qty.as_decimal()).sum();
    qty > Decimal::ZERO
        && fills.iter().try_fold(Decimal::ZERO, |acc, f| {
            acc.checked_add(f.last_qty.as_decimal().checked_mul(f.last_px.as_decimal())?)
        })
        .and_then(|n| n.checked_div(qty))
        .is_some()
}

match manager.aggregate_fill_group(&fills) {
    Ok(r) => handle(r),
    Err(e) if e.to_string().contains("average price is not representable") => {
        log::error!("avg px not representable: {e}");
        quarantine_fills(&fills);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Aggregating a fill group where notional divided by quantity exceeds Decimal capacity or hits a Decimal arithmetic edge — e.g. extremely small quantity with enormous notional, or near-max notional accumulated in the prior fold steps.

Common situations: Downstream symptom of earlier bad fill data: wrongly scaled prices/quantities from an adapter, corrupted fill records, or aggregating fills with astronomically large notional and tiny quantity; precision mismatch in the instrument definition.

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

• fill quantity overflow while aggregating fill group
• fill notional overflow while aggregating fill group
• WETH balance overflow for included transaction {tx_hash} at
• in-flight mutex poisoned
• Batch cancel limit is {endpoint_limit} orders for {product_t

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