nautechsystems/nautilus_trader · error · anyhow::Error

{reason}

Error message

{reason}

What it means

This is the shared failure exit for a Spot WS trading session whose private user data stream could not be established: it marks user data inactive, aborts the session handle, disconnects, and returns the wrapped reason — typically 'WS session logon failed: …', 'WS user data subscribe failed: …', or 'Failed to connect WS trading API: …' (see the call sites around spot/execution.rs:876-910).

Source

Thrown at crates/adapters/binance/src/spot/execution.rs:571

    fn abort_pending_tasks(&self) {
        crate::common::execution::abort_pending_tasks(&self.pending_tasks);
    }

    async fn ws_setup_failure(
        &mut self,
        mut ws_trading: BinanceSpotWsTradingClient,
        reason: String,
    ) -> anyhow::Error {
        ws_trading.mark_user_data_inactive();
        log::error!("{reason}; Binance Spot private user data is required for execution");

        if let Some(handle) = self.ws_trading_handle.take() {
            handle.abort();
        }
        ws_trading.disconnect().await;
        self.ws_trading_client = Some(ws_trading);
        anyhow::anyhow!(reason)
    }

    async fn connect_us_user_data(&mut self) -> anyhow::Result<()> {
        let (api_key, api_secret) = self
            .us_credentials
            .clone()
            .context("Binance US user data credentials are unavailable")?;
        let listen_key = self
            .http_client
            .inner()
            .create_listen_key()
            .await
            .context("failed to create Binance US listen key")?
            .listen_key;
        let url = get_spot_user_stream_url(self.config.base_url_ws.as_deref(), &listen_key);
        let mut ws_user_data = BinanceSpotWsTradingClient::new(
            Some(url),
            api_key,

View on GitHub (pinned to a4b06ed870)

Solutions

  1. Verify the API key/secret pair and that the key permits WebSocket API access
  2. Sync the system clock (NTP) — timestamp skew breaks the logon signature
  3. Check network/proxy reachability of the Binance WS trading endpoint
  4. Disable use_ws_trading to fall back to HTTP REST plus the listen-key user data stream

Example fix

# before
config = BinanceExecClientConfig(use_ws_trading=True)  # logon fails

# after: REST trading + listen-key user data stream
config = BinanceExecClientConfig(use_ws_trading=False)
Defensive patterns

Strategy: retry

Validate before calling

# pre-flight before enabling WS trading
# 1. key/secret valid and WebSocket API access enabled for the key
# 2. host clock NTP-synced (logon signature is timestamp-sensitive)
# 3. ws-api.binance.com reachable (curl/proxy check)
# otherwise start with:
config = BinanceExecClientConfig(use_ws_trading=False)

Try / catch

match connect().await {
    Err(e) if e.to_string().contains("WS session logon failed")
        || e.to_string().contains("WS user data subscribe failed")
        || e.to_string().contains("Failed to connect WS trading API") =>
    {
        // fix credentials/clock/network, then retry connect;
        // meanwhile run with use_ws_trading=false over REST
    }
    other => other?,
}

Prevention

When it happens

Trigger: Connecting with use_ws_trading=true when session.logon fails (bad API key/secret, signature or timestamp errors, key lacking WebSocket API access) or when the subsequent userDataStream.subscribe fails.

Common situations: API keys restricted to REST-only; wrong secret or clock skew breaking the logon signature; networks or proxies blocking the WS trading endpoint; first run after enabling use_ws_trading.

Related errors

AI-assisted analysis of nautechsystems/nautilus_trader@a4b06ed870 (2026-08-16). Data as JSON: /api/errors/5be93e5bc1d6166a. Report an issue: GitHub.