nautechsystems/nautilus_trader · error · anyhow::Error

Failed to start Binance Futures session generation: {e}

Error message

Failed to start Binance Futures session generation: {e}

What it means

Raised in BinanceFuturesExecutionClient::connect when the session-tasks tokio TaskGroup fails to start a new generation, after awaiting session tasks and the user-stream dispatch task. Like the pending-task generation error, it means the client's internal background-task infrastructure could not be (re)armed, so connection setup aborts. It usually signals the task group is in a bad lifecycle state or a task failed during startup.

Source

Thrown at crates/adapters/binance/src/futures/execution.rs:1700

            return Ok(());
        }

        if !self.pending_tasks.is_open() || !self.session_tasks.is_open() {
            self.disconnect().await?;
        }

        if !self.pending_tasks.is_open() {
            self.await_pending_tasks().await?;
            self.pending_tasks.start_generation().map_err(|e| {
                anyhow::anyhow!("Failed to start Binance Futures task generation: {e}")
            })?;
        }

        if !self.session_tasks.is_open() {
            self.await_session_tasks().await?;
            self.await_dispatch_task().await?;
            self.session_tasks.start_generation().map_err(|e| {
                anyhow::anyhow!("Failed to start Binance Futures session generation: {e}")
            })?;
        }

        self.cancellation_token = CancellationToken::new();
        let cancellation_token = self.cancellation_token.clone();
        let ws_client = Arc::clone(&self.ws_client);
        let ws_trading_client = self.ws_trading_client.clone();
        let setup_guard =
            TaskGroupGuard::new(&[&self.session_tasks, &self.pending_tasks], move || {
                cancellation_token.cancel();

                if let Some(client) = ws_client.lock().as_ref() {
                    client.begin_shutdown();
                }

                if let Some(client) = ws_trading_client {
                    client.begin_shutdown();
                }

View on GitHub (pinned to 18893faf8b)

Solutions

  1. Perform a full disconnect() before each reconnect attempt so both task groups restart cleanly.
  2. Inspect the wrapped inner error `{e}` and the preceding logs to find the failing/parked task.
  3. Avoid calling connect() concurrently from multiple places; serialize connection attempts.
  4. Recreate the execution client if the task groups remain permanently closed.

Example fix

// before
// reconnect loop
client.connect().await?;

// after
client.disconnect().await?;
tokio::time::sleep(Duration::from_secs(1)).await;
client.connect().await?;
Defensive patterns

Strategy: try-catch

Try / catch

match client.connect().await {
    Err(e) if e.to_string().contains("session generation") => {
        client.disconnect().await?;
        tokio::time::sleep(Duration::from_secs(1)).await;
        client.connect().await?;
    }
    r => r?,
}

Prevention

When it happens

Trigger: connect() called while session_tasks group is closed and await_session_tasks()/await_dispatch_task() complete but session_tasks.start_generation() fails — e.g. after an unclean prior disconnect, a task panic, or runtime shutdown concurrent with connect.

Common situations: Restarting a live node after an error without full teardown, reconnect loops that do not await proper disconnect, or stopping the trader while the WebSocket session tasks are still winding down.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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