What causes "Order {client_order_id} not found in cache." in nautechsystems/nautilus_trader?

Ensure all linked/child orders are submitted through the same node and remain in cache while the parent is active.

Order {client_order_id} not found in cache.

Error message

Order {client_order_id} not found in cache.

What it means

While processing contingent-order bookkeeping for a parent order, the engine iterated linked_order_ids and found a linked child order missing from the cache (order_snapshot returned None), then panicked. Every order linked to a parent must be present in the engine cache for correct contingency lifecycle handling. Its absence means broken chain state or a stale ID.

Source

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

    fn update_contingent_order(&mut self, order: &OrderAny, parent_quantity: Quantity) {
        log::debug!(
            "Updating contingent orders from {}",
            order.client_order_id()
        );

        if let Some(linked_order_ids) = order.linked_order_ids() {
            let parent_filled_qty = self
                .cached_filled_qty
                .get(&order.client_order_id())
                .copied()
                .unwrap_or(order.filled_qty());
            let parent_leaves_qty = parent_quantity.saturating_sub(parent_filled_qty);

            for client_order_id in linked_order_ids {
                let child_order = match self.order_snapshot(*client_order_id) {
                    Some(order) => order,
                    None => panic!("Order {client_order_id} not found in cache."),
                };

                if child_order.is_active_local() {
                    continue;
                }

                let child_filled_qty = self
                    .cached_filled_qty
                    .get(&child_order.client_order_id())
                    .copied()
                    .unwrap_or(child_order.filled_qty());

                if parent_leaves_qty.is_zero() {
                    self.cancel_order(&child_order, Some(false));
                } else if child_filled_qty >= parent_leaves_qty {
                    // Child already filled beyond parent's remaining qty, cancel it
                    self.cancel_order(&child_order, Some(false));
                } else {

View on GitHub (pinned to 18893faf8b)

Solutions

Ensure all linked/child orders are submitted through the same node and remain in cache while the parent is active.
Enable cache persistence or rebuild contingency links during reconciliation after restart.
Purge parent and children together so stale IDs pointing to removed children do not linger.
Pre-check linked IDs against the cache before triggering the contingent update path.

Example fix

// before
engine.handle_event(&parent_filled_event); // triggers contingent update with stale links
// after
let missing: Vec<_> = parent.linked_order_ids().unwrap_or_default()
    .iter().filter(|id| cache.order(id).is_none()).collect();
assert!(missing.is_empty(), "uncached linked orders: {missing:?}");

Defensive patterns

Strategy: validation

Validate before calling

let missing: Vec<_> = parent.linked_order_ids().unwrap_or_default()
    .iter().filter(|id| engine.order_snapshot(id).is_none()).collect();
if !missing.is_empty() { return Err(anyhow!("linked orders not cached: {missing:?}")); }

Type guard

fn all_links_cached(engine: &OrderMatchingEngine, order: &OrderAny) -> bool {
    order.linked_order_ids().map_or(true, |ids| ids.iter().all(|id| engine.order_snapshot(id).is_some()))
}

Prevention

Submit and track all linked child orders on the same node as the parent.
Enable cache persistence so chains survive restarts.
Purge parent and children together to avoid stale links.
Monitor for linked IDs absent from the cache as an early warning.

When it happens

Trigger: Executing the contingent-update path (near matching_engine/mod.rs:6325) where `for client_order_id in linked_order_ids` hits an ID with no cached snapshot.

Common situations: Cache evicted or never contained the child (e.g. child submitted on another node); cache lost on restart without persistence; stale linked_order_ids referencing long-finalized orders that were purged.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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