wavetermdev/waveterm · error

error starting conn server: %w

Error message

error starting conn server: %w

What it means

tryEnableWsh wraps a failure from StartConnServer(ctx, false) with this error. The connserver (wsh server) process inside the WSL distro failed to start or respond on the first attempt, so wsh setup aborts with NoWshReason 'error starting connserver'.

Source

Thrown at pkg/wslconn/wslconn.go:613

		allowInstall, err := conn.getPermissionToInstallWsh(ctx, clientDisplayName)
		if err != nil {
			log.Printf("error getting permission to install wsh: %v\n", err)
			return WshCheckResult{NoWshReason: "error getting user permission to install", WshError: err}
		}
		if !allowInstall {
			return WshCheckResult{NoWshReason: "user selected not to install wsh extensions"}
		}
	}
	err := conn.OpenDomainSocketListener(ctx)
	if err != nil {
		conn.Infof(ctx, "ERROR opening domain socket listener: %v\n", err)
		err = fmt.Errorf("error opening domain socket listener: %w", err)
		return WshCheckResult{NoWshReason: "error opening domain socket", WshError: err}
	}
	needsInstall, clientVersion, osArchStr, err := conn.StartConnServer(ctx, false)
	if err != nil {
		conn.Infof(ctx, "ERROR starting conn server: %v\n", err)
		err = fmt.Errorf("error starting conn server: %w", err)
		return WshCheckResult{NoWshReason: "error starting connserver", WshError: err}
	}
	if needsInstall {
		conn.Infof(ctx, "connserver needs to be (re)installed\n")
		err = conn.InstallWsh(ctx, osArchStr)
		if err != nil {
			conn.Infof(ctx, "ERROR installing wsh: %v\n", err)
			err = fmt.Errorf("error installing wsh: %w", err)
			return WshCheckResult{NoWshReason: "error installing wsh/connserver", WshError: err}
		}
		needsInstall, clientVersion, _, err = conn.StartConnServer(ctx, true)
		if err != nil {
			conn.Infof(ctx, "ERROR starting conn server (after install): %v\n", err)
			err = fmt.Errorf("error starting conn server (after install): %w", err)
			return WshCheckResult{NoWshReason: "error starting connserver", WshError: err}
		}
		if needsInstall {
			conn.Infof(ctx, "conn server not installed correctly (after install)\n")

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the wrapped underlying error to distinguish timeout vs missing binary
2. Ensure wsh is installed in the distro: run 'wsh install' or let InstallWsh retry (the code does this only when needsInstall=true)
3. Update wsh in the distro ('wsh upgrade') to match the Wave client version
4. Check for slow/hanging shell rc files inside the distro that delay server startup
5. Restart the distro (wsl --shutdown) and reconnect

// ensure distro is up and wsh binary present before connecting
if err := exec.Command("wsl", "-d", distro, "--", "bash", "-c", "echo ok").Run(); err != nil {
    return fmt.Errorf("distro not starting: %w", err)
}

res, err := tryEnableWsh(ctx, conn)
if err != nil && strings.Contains(err.Error(), "error starting conn server") {
    // retry after a short wait; slow distros often just need time
    time.Sleep(3 * time.Second)
    res, err = tryEnableWsh(ctx, conn)
}

When it happens

Trigger: StartConnServer fails on the initial probe — the wsh binary is missing or incompatible in the distro, the RPC handshake times out, or the domain socket exists but no server answers.

Common situations: wsh was never installed in a fresh distro, wsh version too old for the client, distro's shell init scripts hang so the server never starts, distro is suspended mid-startup.

Related errors

• unable to obtain client info: %w
• timeout waiting for connserver to register
• error starting conn server (after install): %w
• conn server not installed correctly (after install)
• nil wshrpc passed to wshclient

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/a2d9982f2f407750. Report an issue: GitHub.