netbirdio/netbird · error

WebSocket connection failed

Error message

WebSocket connection failed

What it means

Sentinel error from the browser/WASM gRPC dialer. The JavaScript WebSocket's onerror handler pushes this error into the dialer's channel, and WithWebSocketDialer returns it instead of a connection. It fires when the browser itself fails the connection (refused, TLS failure, mixed content) rather than timing out.

Source

Thrown at util/wsproxy/constants.go:18

package wsproxy

import "errors"

// ProxyPath is the base path where the WebSocket proxy is mounted on servers.
const ProxyPath = "/ws-proxy"

// Component paths that are appended to ProxyPath
const (
	ManagementComponent = "/management"
	SignalComponent     = "/signal"
	FlowComponent       = "/flow"
)

// Common errors
var (
	ErrConnectionTimeout  = errors.New("WebSocket connection timeout")
	ErrConnectionFailed   = errors.New("WebSocket connection failed")
	ErrBackendUnavailable = errors.New("backend unavailable")
)

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Confirm scheme and host: wss for TLS-enabled setups, and that the target serves the /ws-proxy path.
2. Ensure the page's origin is compatible (no https -> ws mixed content).
3. Open the WebSocket URL in the browser devtools console to see the underlying browser error, then fix the proxy or certificate accordingly.

func isWsDialFailed(err error) bool {
    return errors.Is(err, wsproxy.ErrConnectionFailed)
}

conn, err := dialer(ctx)
if err != nil {
    if errors.Is(err, wsproxy.ErrConnectionFailed) {
        // browser refused the WebSocket: TLS/mixed-content/host issue.
        // Retry a couple of times, then fail with guidance to check the URL scheme and proxy
    }
    return err
}

When it happens

Trigger: Connection refused because the host/port is down; TLS error on wss (untrusted or mismatched certificate); mixed-content blocking when an https page opens a ws:// URL; DNS resolution failure in the browser.

Common situations: Serving the WASM app over https while the WebSocket proxy is plain ws; self-signed certificate not trusted by the browser; corporate proxy stripping the WebSocket upgrade.

Related errors

• WebSocket connection timeout
• dial context: %w
• signal receive stream stalled
• failed to check SSO support: %v
• failed to check login requirement: %v

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/9e7cc147f2265538. Report an issue: GitHub.