{"record":{"id":"e74474786c8e0e03","repo":"nautechsystems/nautilus_trader","slug":"failed-to-connect-binance-futures-private-websocke","errorCode":null,"errorMessage":"failed to connect Binance Futures private WebSocket","messagePattern":"failed to connect Binance Futures private WebSocket","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/adapters/binance/src/futures/websocket/streams/recovery.rs","lineNumber":123,"sourceCode":"        Some(BINANCE_WS_HEARTBEAT_SECS),\n        params.transport_backend,\n    )\n    .context(\"failed to construct Binance Futures private WebSocket client\")?\n    .with_proxy(\n        params\n            .proxy_url\n            .as_ref()\n            .map(|value| value.expose_secret().to_owned()),\n    )\n    .with_socket_control(\n        params.socket_factory.clone(),\n        \"binance-futures-user-streams\",\n    );\n\n    log::debug!(\"Connecting to Binance Futures user data stream...\");\n    ws_client.connect().await.map_err(|_| {\n        log::error!(\"Binance Futures private WebSocket connection failed\");\n        anyhow::anyhow!(\"failed to connect Binance Futures private WebSocket\")\n    })?;\n    log::debug!(\"Connected to Binance Futures user data stream\");\n\n    Ok(ws_client)\n}\n\n/// Long-lived task that consumes recovery signals and runs\n/// [`recover_user_data_stream`] with retry-on-failure semantics.\npub(crate) async fn run_recovery_driver<F>(\n    ctx: RecoveryCtx,\n    mut rx: tokio::sync::mpsc::UnboundedReceiver<()>,\n    cancel: CancellationToken,\n    dispatch_fn: F,\n) where\n    F: Fn(BinanceFuturesWsStreamsMessage, &DispatchCtx, &tokio::sync::mpsc::UnboundedSender<()>)\n        + Send\n        + Sync\n        + Clone","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/binance/src/futures/websocket/streams/recovery.rs#L105-L141","documentation":"During user-data-stream recovery, `build_and_connect_user_stream` creates a fresh private WebSocket client for the Binance Futures listen-key stream and awaits `ws_client.connect()`. If the connect future resolves with an error (transport-level failure), the error is swallowed for logging and replaced with this generic anyhow error so `recover_with_retry` will re-attempt. It means the recovered private stream could not be established.","triggerScenarios":"`recover_user_data_stream` (via `recover_with_retry`, typically after a -1125 listen-key invalidation/expiry or dropped connection) calls `connect`, and the WebSocket handshake fails — DNS failure, TLS error, proxy blocking wss://, or Binance endpoint unreachable.","commonSituations":"Network outage or firewall/proxy blocking the Binance WS endpoint during recovery; Binance regional endpoint blocked from your host (e.g. restricted jurisdiction); transient DNS failure; listen-key recreated but network flap at the same time.","solutions":["Check network connectivity to the Binance Futures WS endpoint (DNS, TLS, firewall/proxy); retry — `recover_with_retry` already schedules further attempts.","Verify API key validity and that a valid listen-key was created (a bad key fails the stream after connect).","Confirm no regional/IP restriction applies (Binance blocks some jurisdictions/IPs).","Inspect the preceding `log::error!` output and enable debug logging for the underlying transport for the concrete cause."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Recovery already retries via recover_with_retry; add bounded outer handling\nmatch stream.recover_with_retry(max_attempts).await {\n    Ok(()) => {},\n    Err(e) if e.to_string().contains(\"failed to connect Binance Futures private WebSocket\") => {\n        log::error!(\"recovery connect failed after retries: {e}; check network/listen-key\");\n        // escalate: restart data engine or alert operator\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Ensure outbound WSS (443) to Binance endpoints is allowed by firewall/proxy","Monitor listen-key keepalive so recovery (and thus reconnects) is rare","Verify API key validity and jurisdiction/IP accessibility of the endpoint","Run reconnects with exponential backoff and alert after sustained failure"],"tags":["websocket","network","connection","binance-futures","recovery"],"backgroundTag":"connection-refused","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}