nautechsystems/nautilus_trader · error · anyhow::Error

Binance Futures dispatch task failed

Error message

Binance Futures dispatch task failed: {e}

What it means

await_dispatch_task joins the client's dispatch task (which routes messages from the WebSocket sessions to handlers) and inspects the TaskJoinOutcome; a Failed outcome means the task ended with an error, wrapped in this anyhow message. Called from connect and disconnect, so it can fail both initial connection setup and teardown.

Solutions

  1. Inspect the error chain for the underlying task error (the {e} in the message)
  2. Reconnect — if connect failed, retry after verifying network and API status
  3. Check subscribed data/instrument handlers for panics or errors that crash the dispatcher
  4. Upgrade to the latest nautilus_trader version for dispatcher robustness fixes

Example fix

// before
client.connect().await?;
// after
match client.connect().await {
    Ok(()) => {},
    Err(e) if e.to_string().contains("dispatch task failed") => {
        tracing::error!("dispatch failure: {e:#}");
        tokio::time::sleep(Duration::from_secs(2)).await;
        client.connect().await?; // retry
    }
    Err(e) => return Err(e),
}
Defensive patterns

Strategy: retry

Try / catch

if let Err(e) = client.connect().await {
    if e.to_string().contains("dispatch task failed") {
        tokio::time::sleep(Duration::from_secs(2)).await;
        client.connect().await?;
    } else { return Err(e); }
}

Prevention

When it happens

Trigger: Connecting or disconnecting when the dispatch task panicked or returned an error — e.g. a send handler error, deserialization panic in the message loop, or channel closure while the dispatcher was processing.

Common situations: Exchange sending malformed/unexpected frames that break the dispatch loop, a bug in a subscribed data handler, or abrupt channel teardown during disconnect racing in-flight messages.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

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

    }

    async fn await_dispatch_task(&self) -> anyhow::Result<()> {
        let _recovery_guard = self.recovery_lock.lock().await;
        let mut task_slot = self.ws_task.lock().await;
        let Some(outcome) = finish_task(
            &mut task_slot,
            Duration::from_secs(1),
            Duration::from_secs(2),
        )
        .await
        else {
            return Ok(());
        };

        match outcome {
            TaskJoinOutcome::Completed(()) | TaskJoinOutcome::Aborted => Ok(()),
            TaskJoinOutcome::Failed(e) => {
                Err(anyhow::anyhow!("Binance Futures dispatch task failed: {e}"))
            }
            TaskJoinOutcome::Incomplete => Err(anyhow::anyhow!(
                "Binance Futures dispatch task did not stop after abort"
            )),
        }
    }

    async fn close_listen_key_slot(
        &self,
        slot: &RwLock<Option<SecretString>>,
        context: &str,
    ) -> anyhow::Result<()> {
        let key = slot.read().clone();
        let Some(key) = key else {
            return Ok(());
        };

        self.http_client

View on GitHub (pinned to 18893faf8b)