nautechsystems/nautilus_trader · critical

Order for {} not found to determine position ID

Error message

Order for {} not found to determine position ID

What it means

The execution engine received an order fill event but could not locate the corresponding order in the cache, so it cannot determine the position ID to attribute the fill to. NautilusTrader treats this as an unrecoverable internal inconsistency: a fill can only exist for an order the engine has seen, so it panics rather than silently dropping the fill. This indicates a state synchronization bug between the client/engine and the cache.

Source

Thrown at crates/execution/src/engine/mod.rs:3296

        let position_id = match (oms_type, fill.position_id) {
            (OmsType::Hedging, Some(position_id)) => position_id,
            (OmsType::Hedging, None) => self.determine_hedging_position_id(fill, order),
            (OmsType::Netting, _) => self.determine_netting_position_id(fill),
            _ => self.determine_netting_position_id(fill),
        };

        if !self.validate_fill_for_position(position_id, fill) {
            return None;
        }

        let order = if let Some(o) = order {
            o.clone()
        } else {
            let cache = self.cache.borrow();
            cache.order(&fill.client_order_id()).map_or_else(
                || {
                    panic!(
                        "Order for {} not found to determine position ID",
                        fill.client_order_id()
                    )
                },
                |o| o.clone(),
            )
        };

        if order.exec_algorithm_id().is_some()
            && let Some(exec_spawn_id) = order.exec_spawn_id()
        {
            let cache = self.cache.borrow();
            let primary = if let Some(p) = cache.order(&exec_spawn_id) {
                p.clone()
            } else {
                log::warn!(
                    "Primary exec spawn order {exec_spawn_id} not found, \
                     skipping position ID propagation"

View on GitHub (pinned to 18893faf8b)

Solutions

1. Pass the order explicitly to the fill-handling call so the cache lookup is not needed (the `order: Option<OrderAny>` parameter).
2. Verify the order was successfully submitted and stored in the cache before the fill event is processed; check that client_order_id values match between client and engine.
3. Check cache retention/cleanup configuration (e.g. purge settings) so orders are not removed while fills are still in flight.
4. If this arises during reconciliation, ensure the reconciliation flow creates/updates the local order from the order report before processing the fill report.

Example fix

// before
engine.process_fill(&fill, None);
// after
let order = cache.borrow().order(&fill.client_order_id());
engine.process_fill(&fill, order); // pass the cached order explicitly

// Rust
let order = cache.borrow().order(&fill.client_order_id());
if order.is_none() {
    // skip or request order status before processing the fill
    return Err(anyhow!("order {} not cached; cannot process fill", fill.client_order_id()));
}

fn order_in_cache(cache: &Cache, id: &ClientOrderId) -> Option<OrderAny> {
    cache.order(id)
}

When it happens

Trigger: Calling the fill-handling path (e.g. via ExecEngineFunctions.handle_fill / process_fill for a Fill or OrderFilled event) with fill.client_order_id() that has no matching order in the cache and no explicit `order` argument passed in.

Common situations: Applying a reconciliation fill report for an order that was purged or never stored in the execution cache; running with cache persistence/cleanup that removed the order before the fill arrives; an exec client emitting a fill for an order submitted by a different node instance sharing the same venue.

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

• Order {client_order_id} not found
• Position {position_id} not found
• Order {client_order_id} not found in cache.
• venue-leg quantity calculation validated cumulative fills
• DataActor must be registered before accessing cache

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