{"record":{"id":"0ae0b91b4987dbba","repo":"nautechsystems/nautilus_trader","slug":"binance-futures-position-has-unresolved-instrument","errorCode":null,"errorMessage":"Binance Futures position has unresolved instrument {instrument_id}","messagePattern":"Binance Futures position has unresolved instrument (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/binance/src/futures/execution.rs","lineNumber":2230,"sourceCode":"                    );\n                    continue;\n                }\n            };\n\n            if position_amt.is_zero() {\n                continue;\n            }\n\n            let instrument_id = format_instrument_id(&position.symbol, self.product_type);\n            let Some(instrument) = self.http_client.instrument_reconciliation(&instrument_id)\n            else {\n                if self.is_instrument_out_of_scope(instrument_id) {\n                    log::debug!(\n                        \"Dropping out-of-scope Binance Futures position for instrument {instrument_id}\"\n                    );\n                    continue;\n                }\n                anyhow::bail!(\"Binance Futures position has unresolved instrument {instrument_id}\");\n            };\n\n            match self.create_position_report(\n                &position,\n                instrument.id(),\n                instrument.size_precision(),\n            ) {\n                Ok(report) => reports.push(report),\n                Err(e) => {\n                    log::warn!(\n                        \"Failed to create Futures position report for symbol={}: {e}\",\n                        position.symbol\n                    );\n                }\n            }\n        }\n\n        Ok(reports)","sourceCodeStart":2212,"sourceCodeEnd":2248,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/d1527c24afdf475115785557f89a55c3e336c51f/crates/adapters/binance/src/futures/execution.rs#L2212-L2248","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the affected instrument_id to the instrument provider load_ids (or widen filters) so the definition is cached before reconciliation","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","Close or settle the stray position on the exchange if it is not part of the strategy's scope","Retry reconciliation after instruments finish loading (ensure instruments are loaded before generate_position_status_reports runs)"],"exampleFix":"// nautilus_config.toml\n// before\n[execution_clients.binance_futures.instrument_provider]\nload_ids = [\"BTCUSDT-PERP.BINANCE\"]\n// after\n[execution_clients.binance_futures.instrument_provider]\nload_ids = [\"BTCUSDT-PERP.BINANCE\", \"ETHUSDT-PERP.BINANCE\"]","handlingStrategy":"validation","validationCode":"let instrument = cache.instrument(instrument_id);\nif instrument.is_none() {\n    log::warn!(\"Skipping position report for unresolved {instrument_id}; load the instrument first\");\n}\nassert!(instrument.is_some(), \"instrument must be loaded before reconciliation\");","typeGuard":null,"tryCatchPattern":"match client.generate_position_status_reports(instrument_id).await {\n    Ok(reports) => { /* ... */ }\n    Err(e) if e.to_string().contains(\"unresolved instrument\") => {\n        log::warn!(\"Instrument not loaded: {e}; reloading instruments and skipping this pass\");\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Load all instruments (or configure load_ids covering every market with open positions) before starting reconciliation","Log the instrument cache size at startup to confirm definitions loaded","Re-run reconciliation after any 'instrument not loaded' warning instead of treating it as fatal"],"tags":["binance","futures","reconciliation","instrument","position-report"],"backgroundTag":"unresolved-instrument-id","analyzedSha":"d1527c24afdf475115785557f89a55c3e336c51f","analyzedAt":"2026-08-27T04:01:12.327Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}