nautechsystems/nautilus_trader · error

WS user data subscription timed out

Error message

WS user data subscription timed out

What it means

In Binance Spot WS trading setup, after `subscribe_user_data()` the adapter waits up to `ws_trading_setup_timeout_ms` (default 10,000 ms) for the subscription confirmation (the `ws_user_data_subscribed` Notify). If neither confirmation nor a setup error (e.g. `UserDataSubscriptionRejected`) arrives in time, the timeout error is replaced with 'WS user data subscription timed out' and adapter connection fails before the WS client is registered.

Source

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

    setup_errors: &mut tokio::sync::mpsc::UnboundedReceiver<String>,
    timeout_message: &'static str,
) -> anyhow::Result<()> {
    tokio::pin!(success);

    let result = tokio::time::timeout(timeout, async {
        tokio::select! {
            () = &mut success => Ok(()),
            err = setup_errors.recv() => {
                anyhow::bail!(
                    "{}",
                    err.unwrap_or_else(|| "WS setup error channel closed".to_string()),
                )
            }
        }
    })
    .await;

    result.map_err(|_| anyhow::anyhow!(timeout_message))?
}

#[expect(clippy::too_many_arguments)]
fn dispatch_ws_trading_message(
    msg: BinanceSpotWsTradingMessage,
    emitter: &ExecutionEventEmitter,
    http_client: &BinanceSpotHttpClient,
    account_id: AccountId,
    treat_expired_as_canceled: bool,
    clock: &'static AtomicTime,
    dispatch_state: &WsDispatchState,
    ws_authenticated: &tokio::sync::Notify,
    ws_user_data_subscribed: &tokio::sync::Notify,
    ws_setup_error_tx: &tokio::sync::mpsc::UnboundedSender<String>,
    seen_trade_ids: &std::sync::Arc<Mutex<FifoCache<(Ustr, i64), 10_000>>>,
) {
    match msg {
        BinanceSpotWsTradingMessage::OrderAccepted {

View on GitHub (pinned to a4b06ed870)

Solutions

1. Increase `ws_trading_setup_timeout_ms` (e.g. 30_000) so the subscription confirmation has time to arrive
2. Retry the connect; user-data stream provisioning lag is usually transient
3. Verify network path/proxy to Binance WS endpoints and reduce latency
4. If it consistently fails while authentication succeeds, check for Binance user-data-stream incidents and any account restrictions

Example fix

# before
config = BinanceExecClientConfig(
    api_key=os.environ["BINANCE_API_KEY"],
    api_secret=os.environ["BINANCE_API_SECRET"],
    use_ws_trading=True,  # subscription confirmation must arrive within 10s
)

# after
config = BinanceExecClientConfig(
    api_key=os.environ["BINANCE_API_KEY"],
    api_secret=os.environ["BINANCE_API_SECRET"],
    use_ws_trading=True,
    ws_trading_setup_timeout_ms=30_000,
)

# Python: budget the setup timeout generously when WS trading is enabled
config = BinanceExecClientConfig(
    api_key=..., api_secret=..., use_ws_trading=True,
    ws_trading_setup_timeout_ms=30_000,  # covers slow user-data stream provisioning
)

When it happens

Trigger: Authenticating the WS trading session successfully, but the user-data stream subscription confirmation never arrives within the configured window — stalled WS connection, high latency to Binance, slow user-data stream provisioning, or `ws_trading_setup_timeout_ms` set too low for the round trip.

Common situations: Same contexts as the auth timeout: remote/cross-region hosting, congested networks, Binance maintenance or high load, lowered timeout config; also listen-key/user-data stream provisioning lagging on Binance's side.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• WS session authentication timed out
• WS modify order failed: {e}
• Timeout waiting for account {account_id} to be registered af
• failed to connect Binance Futures private WebSocket
• Binance Spot user data stream is not active

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