nautechsystems/nautilus_trader · error

fill queue availability was checked before cache mutation

Error message

fill queue availability was checked before cache mutation

What it means

While applying order events, the manager unwraps an optional fill queue with `.expect("fill queue availability was checked before cache mutation")`. The surrounding pipeline is supposed to have verified the queue exists before any cache mutation; reaching this line with `fill_queue == None` means that internal invariant was broken. On stock code this should be unreachable and indicates a bug (e.g. in a patched build or an out-of-order event path).

Source

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

                matches!(
                    event,
                    OrderEventAny::Canceled(_) | OrderEventAny::Expired(_),
                )
            }) {
                order_events.pop()
            } else {
                None
            };

            if order_events
                .last()
                .is_some_and(|event| matches!(event, OrderEventAny::Filled(_)))
            {
                order_events.pop();
            }

            let fill_queue =
                fill_queue.expect("fill queue availability was checked before cache mutation");
            for (fill_event, fill_key) in prepared_fills {
                fill_queue.push(&mut order_events, fill_event, fill_key);
            }

            if !defer_terminal
                && let Some(inferred_qty) = inferred_qty
                && let Some(inferred_fill) = create_inferred_fill_for_qty(
                    &order,
                    report,
                    &account_id,
                    instrument,
                    inferred_qty,
                    ts_now,
                    inferred_commission,
                )
            {
                order_events.push(inferred_fill);
            }

View on GitHub (pinned to 18893faf8b)

Solutions

1. On stock nautilus, capture the full log/stacktrace and report a bug — this invariant should hold
2. In custom code, verify the queue-availability check runs before any cache mutation and before `order_events.pop()`
3. Ensure fills are only emitted for orders registered with the execution manager (correct venue/routing)
4. Replace the `expect` with an error return including order id and venue context to aid diagnosis in patched builds

Example fix

// before
let fill_queue = fill_queue.expect("fill queue availability was checked before cache mutation");
// after
let fill_queue = fill_queue.ok_or_else(||
    anyhow::anyhow!("fill queue missing for order {} before cache mutation", client_order_id))?;

if fill_queue.is_none() && !prepared_fills.is_empty() {
    return Err(anyhow::anyhow!("fill queue unavailable while fills pending"));
}

fn fill_queue_ready(fq: &Option<FillQueue>, prepared: &[PreparedFill]) -> bool {
    fq.is_some() || prepared.is_empty()
}

let fq = fill_queue.ok_or_else(|| anyhow!("fill queue missing before cache mutation"))?;

When it happens

Trigger: A path where `prepared_fills` is non-empty but the fill-queue lookup returned `None` — e.g. custom modifications that moved the availability check after cache mutation, or an adapter emitting fills for an order whose execution queue was never registered.

Common situations: Custom forks/patches of the live execution manager; out-of-order event handling where a fill arrives before queue registration; concurrency bugs mutating the order cache between check and use in modified builds.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Order for {} not found to determine position ID
• Close command should not be drained
• Flush command should not be drained
• Order invariant violated: first event must be OrderInitializ
• fill group is empty

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