What causes "Failed to start Spot public JSON WS handler task: {e}" in nautechsystems/nautilus_trader?

Retry connect/subscribe; a transient spawn/start failure usually clears on the next attempt.

Failed to start Spot public JSON WS handler task: {e}

Error message

Failed to start Spot public JSON WS handler task: {e}

What it means

The final startup step of create_connection — spawning the handler task for the slot — failed with error `e`. Before bailing, the code rolls back the already-started bytes task (collecting shutdown_errors) and includes any rollback failures in the message. The slot connection is not usable.

Source

Thrown at crates/adapters/binance/src/spot/websocket/public_json/client.rs:664

                }
            }
        }) {
            cancellation_token.cancel();
            bytes_task.abort();
            let mut shutdown_errors = Vec::new();

            if let Some(error) =
                finish_slot_task(&mut handler_task, "Binance Spot public JSON handler").await
            {
                shutdown_errors.push(error);
            }

            if let Some(error) =
                finish_slot_task(&mut bytes_task, "Binance Spot public JSON bytes").await
            {
                shutdown_errors.push(error);
            }
            anyhow::bail!(if shutdown_errors.is_empty() {
                format!("Failed to start Spot public JSON WS handler task: {e}")
            } else {
                format!(
                    "Failed to start Spot public JSON WS handler task: {e}; startup rollback failed: \
                     {}",
                    shutdown_errors.join("; ")
                )
            });
        }

        if let Some(control) = &socket_control {
            control.register(move || reconnect_handle.request_reconnect());
        }

        Ok(ConnectionSlot {
            cmd_tx,
            streams: Vec::new(),
            handler_task,

View on GitHub (pinned to 18893faf8b)

Solutions

Retry connect/subscribe; a transient spawn/start failure usually clears on the next attempt.
If the message contains 'startup rollback failed' segments, inspect them for leaked bytes-task errors indicating deeper runtime problems.
Ensure connection creation happens on a live, non-shutting-down tokio runtime.
Check system resources (task/thread limits) if spawn failures persist.

Defensive patterns

Strategy: retry

Try / catch

for attempt in 0..3 {
    match client.connect().await {
        Ok(()) => break,
        Err(e) if e.to_string().contains("handler task") && attempt < 2 => tokio::time::sleep(backoff(attempt)).await,
        Err(e) => return Err(e),
    }
}

Prevention

Avoid establishing connections during process/runtime shutdown.
Monitor tokio task counts to avoid spawn failures from resource exhaustion.
Retry connection startup with bounded backoff; spawn failures are often transient.
Inspect rollback-error suffixes for root causes in earlier startup steps.

When it happens

Trigger: create_connection (via connect or subscribe) when the handler task fails to spawn or dies immediately — runtime spawn failure, runtime shutdown in progress, or handler setup erroring on its first poll.

Common situations: Creating WS connections during process/runtime teardown; tokio task limits hit; a handler that depends on a channel that was already closed by an earlier failure.

Related errors

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