nautechsystems/nautilus_trader · error

Binance Futures position has unresolved instrument {instrume

Error message

Binance Futures position has unresolved instrument {instrument_id}

What it means

Thrown during Binance Futures position status report generation when the venue reports an open position for an instrument_id that cannot be resolved in the local instrument cache (after out-of-scope filtering). The execution client cannot build a PositionReport without the instrument's precision/definition, so reconciliation aborts. It usually means the instrument definitions were never loaded or subscribed for that symbol.

Source

Thrown at crates/adapters/binance/src/futures/execution.rs:2230

                    );
                    continue;
                }
            };

            if position_amt.is_zero() {
                continue;
            }

            let instrument_id = format_instrument_id(&position.symbol, self.product_type);
            let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id)
            else {
                if self.is_instrument_out_of_scope(instrument_id) {
                    log::debug!(
                        "Dropping out-of-scope Binance Futures position for instrument {instrument_id}"
                    );
                    continue;
                }
                anyhow::bail!("Binance Futures position has unresolved instrument {instrument_id}");
            };

            match self.create_position_report(
                &position,
                instrument.id(),
                instrument.size_precision(),
            ) {
                Ok(report) => reports.push(report),
                Err(e) => {
                    log::warn!(
                        "Failed to create Futures position report for symbol={}: {e}",
                        position.symbol
                    );
                }
            }
        }

        Ok(reports)

View on GitHub (pinned to d1527c24af)

Solutions

1. Add the affected instrument_id to the instrument provider load_ids (or widen filters) so the definition is cached before reconciliation
2. Verify the instrument was actually fetched: check debug logs for 'Dropping out-of-scope Binance Futures position' vs this bail to distinguish scope filtering from a cache miss
3. Close or settle the stray position on the exchange if it is not part of the strategy's scope
4. Retry reconciliation after instruments finish loading (ensure instruments are loaded before generate_position_status_reports runs)

Example fix

// nautilus_config.toml
// before
[execution_clients.binance_futures.instrument_provider]
load_ids = ["BTCUSDT-PERP.BINANCE"]
// after
[execution_clients.binance_futures.instrument_provider]
load_ids = ["BTCUSDT-PERP.BINANCE", "ETHUSDT-PERP.BINANCE"]

let instrument = cache.instrument(instrument_id);
if instrument.is_none() {
    log::warn!("Skipping position report for unresolved {instrument_id}; load the instrument first");
}
assert!(instrument.is_some(), "instrument must be loaded before reconciliation");

match client.generate_position_status_reports(instrument_id).await {
    Ok(reports) => { /* ... */ }
    Err(e) if e.to_string().contains("unresolved instrument") => {
        log::warn!("Instrument not loaded: {e}; reloading instruments and skipping this pass");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling generate_position_status_reports (typically via ExecutionEngine.generate_position_status_reports on connect/reconciliation) while Binance Futures returns a position for a symbol missing from the InstrumentProvider cache; e.g. a new perpetual listing, a manually opened position on an instrument not in the configured scope, or instrument loading restricted by config.

Common situations: Starting a live TradingNode with instrument load filters (config.instrument_provider.load_ids) that omit a symbol with an existing position; a newly listed contract added after the node's instrument snapshot; partial instrument fetch failure during startup.

Related errors

• Binance Futures open order request has unresolved instrument
• Binance Futures open order has unresolved instrument {instru
• Binance Futures open algo order has unresolved instrument {i
• Instrument not found in cache: {symbol}
• `close_position` cannot be combined with `reduce_only` on Bi

AI-assisted analysis of nautechsystems/nautilus_trader@d1527c24af (2026-08-27). Data as JSON: /api/errors/0ae0b91b4987dbba. Report an issue: GitHub.