nautechsystems/nautilus_trader · error · anyhow::Error

failed to connect Binance Futures market WebSocket

Error message

failed to connect Binance Futures market WebSocket: {e}

What it means

During BinanceFuturesDataClient::connect, the primary market data WebSocket failed to establish a connection. The underlying WebSocket client error is logged with debug formatting and surfaced as an anyhow error, aborting the whole async connect block (the public WebSocket is never attempted).

Solutions

  1. Check network egress to the Binance Futures WebSocket host (port 443 reachable) and fix proxy/firewall settings
  2. Read the logged `Binance Futures market WebSocket connection failed: {e:?}` line for the root cause
  3. Retry with backoff — transient outages and TLS handoff failures resolve themselves
  4. Verify the configured base URL / testnet flag points at the correct reachable endpoint
Defensive patterns

Strategy: retry

Validate before calling

// before connecting, verify the endpoint is reachable
assert!(std::net::TcpStream::connect("fstream.binance.com:443").is_ok(), "Binance Futures WS endpoint unreachable");

Try / catch

loop {
    match client.connect().await {
        Ok(()) => break,
        Err(e) if e.to_string().contains("failed to connect Binance Futures market WebSocket") => {
            log::warn!("WS connect failed: {e}; retrying in 5s");
            tokio::time::sleep(Duration::from_secs(5)).await;
        }
        Err(e) => return Err(e),
    }
}

Prevention

When it happens

Trigger: Calling connect() on the Binance Futures data client when self.ws_client.connect() returns Err — DNS failure, TCP/TLS failure to Binance endpoints, proxy blocking, or endpoint outage.

Common situations: Running in an environment without internet egress or behind a corporate proxy/firewall; wrong DNS; Binance geo-blocking (e.g. US IPs to binance.com); transient Binance API downtime.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/00a7569718cfb4b2. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/binance/src/futures/data.rs:1573

        Self::refresh_instrument_catalog(
            &self.http_client,
            &self.config.instrument_provider,
            &self.instruments,
            &self.status_cache,
            &self.ws_client,
            &self.ws_public_client,
            &self.data_sender,
            self.clock,
            false,
        )
        .await?;

        let session_result = async {
            log::info!("Connecting to Binance Futures market WebSocket...");
            self.ws_client.connect().await.map_err(|e| {
                log::error!("Binance Futures market WebSocket connection failed: {e:?}");
                anyhow::anyhow!("failed to connect Binance Futures market WebSocket: {e}")
            })?;
            log::info!("Binance Futures market WebSocket connected");

            log::info!("Connecting to Binance Futures public WebSocket...");
            self.ws_public_client.connect().await.map_err(|e| {
                log::error!("Binance Futures public WebSocket connection failed: {e:?}");
                anyhow::anyhow!("failed to connect Binance Futures public WebSocket: {e}")
            })?;
            log::info!("Binance Futures public WebSocket connected");

            let stream = self.ws_client.stream();
            let sender = self.data_sender.clone();
            let insts = self.instruments.clone();
            let ws_insts = self.ws_client.instruments_cache();
            let buffers = self.book_buffers.clone();
            let book_subs = self.book_subscriptions.clone();
            let l1_book_subs = self.l1_book_subscriptions.clone();
            let force_order_refs = self.force_order_refs.clone();

View on GitHub (pinned to 18893faf8b)