If you trade physically-settled futures (gold, ag, energy, metals, livestock) live on Interactive Brokers via QuantConnect, you may have hit a problem that doesn't appear in backtesting: IBKR force-liquidates physically-settled contracts well before exchange last-trading-day, but LEAN's continuous-future mapping modes (OpenInterest, LastTradingDay, etc.) don't roll the mapped contract early enough to avoid this.

The result: your held contract gets force-liquidated by IBKR while LEAN's continuous future is still mapped to that contract. Your back-adjusted continuous price series — used for signal generation — diverges from your actual broker-held contract. For commodity futures this can produce material PnL differences relative to a clean backtest.

I've filed a feature request as GitHub issue #9440 proposing two related additions:

  1. A new DataMappingMode.TRADING_DAYS_BEFORE_EXPIRY mode with a configurable roll_offset_trading_days parameter, so users can roll the mapped contract N trading days before exchange expiry to safely beat broker liquidation timing.
  2. A new held_contract_months parameter restricting which expiry months the continuous contract rolls into. This addresses the related issue that some products have listed contract months which are too thinly traded to safely hold (e.g., October gold has weak open interest, May lean hogs has structurally low liquidity).

Both are designed to be additive — existing mapping modes and existing user code remain unchanged.

The full spec, including worked examples, the interaction with contract_depth_offset, and motivation, is in the GitHub issue's comment thread.

A related thread from 2017 raised the same underlying problem: First Notice vs Expiry on futures. The issue has persisted since then without a clean architectural solution.

If this affects your live trading, two things would help:

  • Upvote the GitHub issue with a 👍 reaction (this is how QC's roadmap prioritises features).
  • Comment on this forum thread describing how you've worked around it — manually scheduled close-outs, custom rollover logic, or just avoiding physically-settled futures entirely. Real user experience strengthens the case.


Discussion welcome — happy to clarify any aspect of the proposal or hear from anyone running into adjacent issues.

Thank you.