rathole-org/rathole · error

failed to connect

Error message

failed to connect

What it means

Fires in the websocket transport's connect: after building ws://<addr> and completing the underlying sub-transport (insecure TCP or TLS) connection and handshake, the WebSocket client handshake with the server failed, so no WebSocket stream could be established to the given address. Common causes are the remote endpoint not speaking WebSocket, a wrong path/upgrade response, or TLS failure underneath.

Solutions

1. Verify the target address is a rathole server endpoint with WebSocket transport enabled
2. Check the URL scheme/path matches what the server expects (ws:// vs wss:// per TLS settings)
3. Confirm TLS certificates and SNI are valid when the secure sub-transport is used
4. Check proxies/firewalls that may strip WebSocket Upgrade headers

When it happens

Trigger: Thrown at src/transport/websocket.rs:248 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rathole-org/rathole@a292f7ed54 (2026-09-07). Data as JSON: /api/errors/8b18d3b40014c90e. Report an issue: GitHub.

Appendix: source

Thrown at src/transport/websocket.rs:248

            SubTransport::Secure(t) => TransportStream::Secure(t.handshake(conn).await?),
        };
        let wsstream = accept_async_with_config(tsream, Some(self.conf)).await?;
        let tun = WebsocketTunnel {
            inner: StreamReader::new(StreamWrapper { inner: wsstream }),
        };
        Ok(tun)
    }

    async fn connect(&self, addr: &AddrMaybeCached) -> anyhow::Result<Self::Stream> {
        let u = format!("ws://{}", &addr.addr.as_str());
        let url = Url::parse(&u).unwrap();
        let tstream = match &self.sub {
            SubTransport::Insecure(t) => TransportStream::Insecure(t.connect(addr).await?),
            SubTransport::Secure(t) => TransportStream::Secure(t.connect(addr).await?),
        };
        let (wsstream, _) = client_async_with_config(url, tstream, Some(self.conf))
            .await
            .expect("failed to connect");
        let tun = WebsocketTunnel {
            inner: StreamReader::new(StreamWrapper { inner: wsstream }),
        };
        Ok(tun)
    }
}

View on GitHub (pinned to a292f7ed54)