wavetermdev/waveterm · error

error starting conn server (after install): %w

Error message

error starting conn server (after install): %w

What it means

After a successful InstallWsh, tryEnableWsh retries StartConnServer(ctx, true) and wraps any failure with this error. The freshly installed connserver still failed to start, meaning the install/launch pipeline did not produce a working server despite the install succeeding.

Source

Thrown at pkg/wslconn/wslconn.go:627

	}
	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")
			err = fmt.Errorf("conn server not installed correctly (after install)")
			return WshCheckResult{NoWshReason: "connserver not installed properly", WshError: err}
		}
		return WshCheckResult{WshEnabled: true, ClientVersion: clientVersion}
	} else {
		return WshCheckResult{WshEnabled: true, ClientVersion: clientVersion}
	}
}

func (conn *WslConn) getConnectionConfig() (wconfig.ConnKeywords, bool) {
	config := wconfig.GetWatcher().GetFullConfig()
	connSettings, ok := config.Connections[conn.GetName()]
	if !ok {
		return wconfig.ConnKeywords{}, false

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the installed binary's architecture matches the distro (osArchStr) and is executable
2. Kill stale connserver processes inside the distro and clear ~/.wsh sockets, then reconnect
3. Check for noexec on the home filesystem; relocate WSL's home or remount
4. Increase patience: restart the distro (wsl --shutdown) and connect once cleanly
5. Run 'wsh connserver status'/'~/.wsh/bin/wsh --version' inside the distro to debug directly

// confirm the binary is executable and arch-correct before relying on the install
out, _ := exec.Command("wsl", "-d", distro, "--", "bash", "-c",
    "file ~/.wsh/bin/wsh && test -x ~/.wsh/bin/wsh && echo OK").CombinedOutput()
if !strings.Contains(string(out), "OK") {
    return fmt.Errorf("wsh binary not executable or wrong arch")
}

res, err := tryEnableWsh(ctx, conn)
if err != nil && strings.Contains(err.Error(), "after install") {
    // one clean restart usually clears stale processes/sockets
    exec.Command("wsl", "--shutdown").Run()
    time.Sleep(2 * time.Second)
    res, err = connectAndEnable(ctx, conn)
}

When it happens

Trigger: StartConnServer(ctx, true) fails immediately after InstallWsh succeeded — the newly installed binary can't execute (wrong arch, missing exec permission), the domain socket wasn't refreshed, or startup handshake times out.

Common situations: Architecture mismatch (e.g. arm64 vs x64 binary), noexec mount on the distro home filesystem, lingering old connserver process holding the socket, very slow distro boot exceeding the startup timeout.

Related errors

• error starting conn server: %w
• conn server not installed correctly (after install)
• SwapToken is required in CommandOptsType
• unable to obtain client info: %w
• error checking wsh version: %w

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