[Reconciliation] LiveExecEngine fails to reconcile long-lived Binance Futures positions for HEDGING

[willjay97]

Bug Report

Expected Behavior

With reconciliation=True, restarting should reconcile execution state even for positions open >10 days. Local position net quantity should match the venue’s report, and the strategy will not be started.

Actual Behavior

Reconciliation fails on restart for a SHORT position on CTKUSDT-PERP (Binance USDT-M) (maybe others, log in this symbol for example). Engine reports a net-qty mismatch and the strategy does not start.

[ERROR] ExecEngine: Cannot reconcile CTKUSDT-PERP.BINANCE PositionId('CTKUSDT-PERP.BINANCE-SHORT'):
position net qty 75 != reported net qty -65,
PositionStatusReport(... position_side=SHORT, quantity=65, signed_decimal_qty=-65, ...)
... ...
[ERROR] TradingNode: Execution state could not be reconciled
😭 The program is paused, will not be started...

The -65 is correct, and the recon result 75 is not accurate.

Steps to Reproduce the Problem

1. Open and hold a position for a long time (>10 days).
2. Start node with reconciliation enabled (config below).
3. Restart the process and observe reconciliation failure.

Code Snippets or Logs

exec_engine = LiveExecEngineConfig(
    reconciliation=True,
    # reconciliation_lookback_mins=1440*10,  # tried larger values; still fails
)
data_engine = LiveDataEngineConfig(
    time_bars_timestamp_on_close=False,
    validate_data_sequence=False,
)
cache = CacheConfig()

Additional Notes / Hypotheses (for maintainers):

1. The mismatch appears only after the position has been open for a long period (>10 days).
2. My understanding is that reconciliation rebuilds local state from a lookback window of executions/fills; if a portion of the historical executions falls outside the window or cannot be fetched, local reconstruction could diverge from the venue’s reported net quantity.
3. I attempted to increase reconciliation_lookback_mins (e.g., 10 days and even larger windows), but the mismatch persists.

Thank you very much for your time for this excellent project! I would greatly appreciate guidance on the reconciliation problem.

Specifications

• OS platform: Ubuntu
• Python version: 3.12
• nautilus_trader version: 1.221.0a20251020

[cjdsellers]

Hi @willjay97

Thanks for reaching out with the detailed report.

I think this is a current limitation in how Nautilus handles position reconciliation for Binance Futures hedge mode (when
dualSidePosition=true).

When you're using hedge mode, Binance reports positions with a venue_position_id set (e.g., CTKUSDT-PERP.BINANCE-SHORT). This is a different reconciliation path in the execution engine that only validates the quantities match - if they don't, it just fails currently. The generate_missing_orders config is completely bypassed in this path.

In contrast, netting mode (the default) goes through a different path that will actually generate synthetic orders to fix position discrepancies when generate_missing_orders=True.

The generation of orders is necessary because Nautilus can only operate with the information it's provided, and if historical orders fall outside the retention window and are not persisted in the cache then they need to be generated to align state.

The fix would be that the hedge mode reconciliation path should also support generating missing orders to align discrepancies, just like netting mode does. For now you could work around this by using netting mode and we'll eventually get to this as part of the reconciliation upgrade coming after the next release - I hope that helps a bit!

[willjay97]

Thank you for your professional reply~

Yes, as you said, I usually set the dualSidePosition=true.

It turned out to be because of "The generate_missing_orders config is completely bypassed in this path."😭. Thank you very much for your explanation of the code path logic. It is very professional and useful.

Drawing on NautilusTrader excellent design ideas, I currently use CCXT to fetch positions and generate position offsets (like "generate synthetic orders to fix position discrepancies") to temporarily solve this problem😆.

Looking forward to NautilusTrader more amazing feature in the future.😍