What causes "Failed to start market shard forwarder: {e}" in nautechsystems/nautilus_trader?

Check network connectivity and the Polymarket websocket URL configuration

Failed to start market shard forwarder: {e}

Error message

Failed to start market shard forwarder: {e}

What it means

Polymarket market shard startup failed: after spawning a new shard connection, if the forwarder task immediately returns an error (e), connect_new_shard rolls back by closing the shard. If the rollback close also fails, both errors are combined into one bail message; otherwise only the original forwarder error is reported.

Source

Thrown at crates/adapters/polymarket/src/websocket/pool.rs:677

            .ok_or_else(|| anyhow::anyhow!("Market shard receiver unavailable after connect"))?;
        let forwarder = match self.spawn_forwarder(rx, is_primary) {
            Ok(forwarder) => forwarder,
            Err((e, forwarder)) => {
                let shard = Box::new(ShardEntry {
                    client,
                    handle,
                    forwarder,
                    owned: 0,
                    closing: true,
                });

                if let Err(close_error) = self.close_shard(id, shard).await {
                    anyhow::bail!(
                        "Failed to start market shard forwarder: {e}; startup rollback failed: \
                         {close_error}"
                    );
                }
                anyhow::bail!("Failed to start market shard forwarder: {e}");
            }
        };

        let shard = ShardEntry {
            client,
            handle,
            forwarder,
            owned: 0,
            closing: false,
        };
        let rejected_shard = {
            let mut state = self.state.lock();

            if self.closed.load(Ordering::Acquire) {
                Some(shard)
            } else {
                state.shards.insert(id, shard);
                None

View on GitHub (pinned to 18893faf8b)

Solutions

Check network connectivity and the Polymarket websocket URL configuration
Inspect the inner error ({e}) in the message — it names the actual forwarder failure; fix that root cause first
If 'startup rollback failed' also appears, investigate why close_shard failed (shutdown_errors accumulated in pool state)
Retry pool assignment; transient connect failures may succeed on a later attempt

Defensive patterns

Strategy: try-catch

Validate before calling

// Before assigning, confirm pool is open and endpoint reachable
// (Rust-style sketch)
if pool.is_closed() { return Err(anyhow::anyhow!("pool closed")); }
// Optionally probe the websocket URL with a quick TCP/TLS connect first

Try / catch

match pool.assign(...).await {
    Ok(id) => /* use shard id */,
    Err(e) if e.to_string().contains("Failed to start market shard forwarder") => {
        log::warn!("shard startup failed: {e:#}; retrying after backoff");
        // backoff then retry
    }
    Err(e) => return Err(e),
}

Prevention

Check pool lifecycle before assigning subscriptions
Monitor the inner forwarder error text to address the true root cause
Apply connection retry/backoff at the application level
Keep Polymarket endpoint configuration current

When it happens

Trigger: Calling assign() on the market connection pool when the pool is open and a new shard must be created, but the spawned forwarder task exits with an error during startup (e.g. websocket connect or subscription failure), and possibly the rollback close_shard also errors.

Common situations: Polymarket websocket endpoint unreachable or dropping connections during shard spin-up; network instability at startup; auth/subscription rejected immediately causing the forwarder to fail before it runs.

Related errors

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