nautechsystems/nautilus_trader · error

OUO quantity overflow for order {client_order_id}

Error message

OUO quantity overflow for order {client_order_id}

What it means

When an OrderUpdated (OUO) event cascades quantity changes to sibling orders (e.g. contingent/OCO legs), the engine caps each sibling's leaves and computes target = sibling.filled_qty + capped leaves with checked addition. Overflow means the sibling's new total quantity is not representable, so the engine raises this error naming the originating client_order_id.

Source

Thrown at crates/execution/src/matching_engine/mod.rs:5526

            };

            if sibling.is_closed() || sibling.is_active_local() || !sibling.is_passive() {
                continue;
            }

            // Cancellation also covers core orders whose acceptance is not yet acknowledged
            if leaves.is_zero() {
                self.cancel_order(&sibling, Some(false));
                continue;
            }

            if !sibling.is_open() {
                continue;
            }

            let leaves = self.parent_capped_leaves(&sibling, leaves);
            let target = sibling.filled_qty().checked_add(leaves).ok_or_else(|| {
                anyhow::anyhow!("OUO quantity overflow for order {client_order_id}")
            })?;

            if sibling.quantity() != target {
                self.generate_order_updated(
                    &sibling,
                    target,
                    sibling.price(),
                    sibling.trigger_price(),
                    None,
                );
            }

            if leaves.is_zero() {
                self.cancel_order(&sibling, Some(false));
            }
        }
        Ok(())
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Clamp the amended/updated quantity passed to the parent order to a sane, representable range before the update.
2. Normalize sibling filled_qty and computed leaves to a common precision before addition.
3. Review the OUO handler at crates/execution/src/matching_engine/mod.rs (~line 5510-5526) and log sibling.filled_qty and leaves to see the overflowing operands.
4. Fix strategy code that generates extreme quantity updates (e.g. percentage-based sizing on zero/degenerate balances).

Example fix

// before: amending parent to an extreme quantity cascades to siblings
engine.modify_order(&order, Some(Quantity::from(u64::MAX)), None)?;
// after: bound the amendment to representable position sizes
let new_qty = new_qty.min(max_representable_qty(instrument));
engine.modify_order(&order, Some(new_qty), None)?;

// clamp amended quantities so sibling targets cannot overflow
let new_qty = requested_qty.min(max_representable_qty);
let target = sibling.filled_qty().checked_add(new_qty - sibling.filled_qty());
assert!(target.is_some(), "sibling target quantity would overflow");

match engine.iteration(&mut command_queue) {
    Err(e) if e.to_string().starts_with("OUO quantity overflow") => {
        log::error!("{e}; aborting quantity cascade for order");
        // cancel the order family and re-issue with bounded quantities
    }
    other => other,
}

When it happens

Trigger: An order-update/replace flow where the parent's new quantity (after capping) is enormous, or sibling filled_qty uses a different precision such that their sum exceeds Decimal capacity during sibling quantity maintenance.

Common situations: OCO/bracket setups where a parent order is amended to an unrealistic quantity; custom strategy code calling modify_order with extreme quantities; high-precision instruments amplifying magnitude.

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

• OTO parent not found
• Cannot find contingent order for {client_order_id}
• Order {client_order_id} not found in cache.
• Pending position quantity overflow
• Reduce-only quantity overflow for order {client_order_id}

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