nautechsystems/nautilus_trader · error · anyhow::Error

client order ID differs across fill group

Error message

client order ID differs across fill group

What it means

create_orphan_fill_order_report collapses a group of FillReports into one synthetic OrderStatusReport, which requires a single client_order_id. This ensure! verifies all fills in the group share the same client_order_id; disagreement means the group mixes fills the trader cannot attribute to one client order, so the aggregation is aborted.

Source

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

        };
        let venue_position_id = first
            .venue_position_id
            .ok_or_else(|| anyhow::anyhow!("venue position ID is missing"))?;

        for fill in fills.iter().skip(1) {
            anyhow::ensure!(
                fill.account_id == first.account_id,
                "account ID differs across fill group"
            );
            anyhow::ensure!(
                fill.instrument_id == first.instrument_id,
                "instrument ID differs across fill group"
            );
            anyhow::ensure!(
                fill.venue_order_id == first.venue_order_id,
                "venue order ID differs across fill group"
            );
            anyhow::ensure!(
                fill.client_order_id == first.client_order_id,
                "client order ID differs across fill group"
            );
            anyhow::ensure!(
                fill.order_side == first.order_side,
                "order side differs across fill group"
            );
            anyhow::ensure!(
                fill.venue_position_id == first.venue_position_id,
                "venue position ID differs across fill group"
            );
        }

        anyhow::ensure!(
            first.instrument_id == instrument.id(),
            "instrument metadata does not match fill group"
        );

View on GitHub (pinned to 18893faf8b)

Solutions

1. Verify all fills for the same venue order were submitted under the same client order ID; re-key the fill group so only fills with identical client_order_id are merged.
2. Check that your adapter assigns client_order_id deterministically (generate_order_status_reports / client ID resolution) rather than leaving it None for some fills.
3. If the order is fully external, ensure the adapter sets the same synthetic client order ID for every fill of that venue order.
4. Clear stale reconciliation/cache state (cached client order ID mappings) that may associate an old client order ID with the order.

Example fix

// before: merged all fills for an instrument into one group
let group: Vec<&FillReport> = fills_by_instrument[&instrument_id].clone();
// after: sub-group by client_order_id so IDs agree
let group: Vec<&FillReport> = fills_by_client_order_id[&client_order_id].clone();

let client_ids: std::collections::HashSet<_> = fills.iter().map(|f| f.client_order_id).collect();
assert!(client_ids.len() == 1, "fill group has mixed client order IDs: {:?}", client_ids);

fn single_client_order_group(fills: &[&FillReport]) -> bool {
    fills.iter().all(|f| f.client_order_id == fills[0].client_order_id)
}

When it happens

Trigger: FillReports grouped together during reconciliation (e.g. orphan fills for an external order) contain different client_order_id values — typically one fill has a client_order_id assigned by Nautilus and another has None or a venue-assigned value.

Common situations: Orders placed outside Nautilus and then partially reconciled, causing mixed ID attribution; adapter reporting some fills with a client order ID and others without (e.g. after a restart or an externally modified order); replayed fill data across sessions with different ID conventions.

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

• venue order ID differs across fill group
• order side differs across fill group
• venue position ID differs across fill group
• Binance Futures position request has unresolved instrument {
• Modify order failed: {e}

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