tracel-ai/burn · critical

Failed to open remote 'data' channel to {address}: {err:?}.

Error message

Failed to open remote 'data' channel to {address}: {err:?}. Is a `burn-remote` server running at that address?

What it means

Before downloading tensors, the client opens a WebSocket connection on the 'data' subprotocol to the remote address. If `P::Client::connect` fails (server unreachable, not a burn-remote server, wrong port, TLS/protocol rejection), the code panics with this message asking whether a `burn-remote` server is running at that address.

Source

Thrown at crates/burn-communication/src/external_comm.rs:189

            return Some(data);
        }
        log::warn!("Closed connection");
        None
    }

    /// Get the WebSocket stream for the given address, or create a new one if it doesn't exist.
    async fn get_data_stream(
        &self,
        address: Address,
    ) -> Arc<Mutex<<P::Client as ProtocolClient>::Channel>> {
        let mut streams = self.channels.lock().await;
        match streams.get(&address) {
            Some(stream) => stream.clone(),
            None => {
                // Open a new WebSocket connection to the address
                let stream = match P::Client::connect(address.clone(), "data").await {
                    Ok(stream) => stream,
                    Err(err) => panic!(
                        "Failed to open remote 'data' channel to {address}: {err:?}. \
                         Is a `burn-remote` server running at that address?"
                    ),
                };

                let stream = Arc::new(Mutex::new(stream));
                streams.insert(address.clone(), stream.clone());

                stream
            }
        }
    }

    /// Get the requested exposed tensor data, and update download counter
    async fn get_exposed_tensor_bytes(
        &self,
        transfer_id: TensorTransferId,
    ) -> Option<bytes::Bytes> {

View on GitHub (pinned to d16f7ba2ed)

Solutions

  1. Start the burn-remote server and verify it listens on the given address (curl/nc the host:port).
  2. Correct the address string (scheme, host, port) used to create the remote client.
  3. Check network reachability (firewall, port mapping, TLS certificates) between client and server.
  4. Confirm server and client speak the same protocol version so the 'data' subprotocol handshake succeeds.

Example fix

// before
let client = RemoteClient::connect("ws://localhost:3999").await; // wrong port, nothing listening
// after
// $ burn-remote-server --port 3000
let client = RemoteClient::connect("ws://localhost:3000").await;
Defensive patterns

Strategy: retry

Validate before calling

// Probe the endpoint before connecting
let reachable = tokio::net::TcpStream::connect(addr).await.is_ok();
if !reachable { return Err(format!("no burn-remote server at {addr}")); }

Try / catch

// Retry with backoff before giving up
for attempt in 0..3 {
    match try_download(&addr).await {
        Ok(d) => return Ok(d),
        Err(e) if attempt < 2 => tokio::time::sleep(Duration::from_secs(1 << attempt)).await,
        Err(e) => return Err(e),
    }
}

Prevention

When it happens

Trigger: Calling remote tensor download (`download_tensor` -> `get_data_stream`) when no server is listening at `address`; the server exists but doesn't accept the "data" subprotocol; wrong scheme/host/port in the address string; firewall or TLS failure.

Common situations: Forgetting to start the burn-remote server before running a remote client; typos in the remote address/port; server bound to a different interface than the client connects to; Docker/K8s port not exposed.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/daac9e0f462b721c. Report an issue: GitHub.