wavetermdev/waveterm · error

conn server not installed correctly (after install)

Error message

conn server not installed correctly (after install)

What it means

This error is thrown when, after installing wsh, StartConnServer(ctx, true) STILL returns needsInstall=true — i.e. the installer claimed success but the server is not actually installed correctly (missing or wrong version). It is a self-check failure in the install->verify loop of tryEnableWsh.

Source

Thrown at pkg/wslconn/wslconn.go:632

		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
	}
	return connSettings, true
}

func (conn *WslConn) persistWshInstalled(ctx context.Context, result WshCheckResult) {

View on GitHub (pinned to a4447c1563)

Solutions

1. Run wsl --shutdown to stop all distros and stale processes, then reconnect once
2. Delete ~/.wsh (or ~/.wsh/bin) inside the distro and reconnect to force a clean reinstall
3. Confirm ~/.wsh/bin/wsh exists and matches the client version inside the exact distro being connected
4. Check disk space and write errors in the distro logs
5. File/report if reproducible — indicates an install-path mismatch bug

Example fix

// clean reinstall path
// wsl -d Ubuntu -- bash -c 'rm -rf ~/.wsh' && wsl --shutdown
// then reconnect from Wave so InstallWsh runs from scratch

// verify install actually landed before trusting the result
out, _ := exec.Command("wsl", "-d", distro, "--", "bash", "-c",
    "test -x ~/.wsh/bin/wsh && ~/.wsh/bin/wsh --version").CombinedOutput()
if len(out) == 0 {
    return fmt.Errorf("wsh not present after install; wiping ~/.wsh for clean reinstall")
}

if err != nil && strings.Contains(err.Error(), "not installed correctly") {
    // fallback: clean reinstall
    exec.Command("wsl", "--shutdown").Run()
    exec.Command("wsl", "-d", distro, "--", "bash", "-c", "rm -rf ~/.wsh").Run()
    return connectAndEnable(ctx, conn) // installer runs from scratch
}

When it happens

Trigger: InstallWsh reports success but the subsequent verify call finds the connserver binary absent/mismatched — install wrote to a different path than StartConnServer checks, a cached old binary is being probed, or the install silently failed (e.g. partial write).

Common situations: Multiple WSL distros with divergent ~/.wsh states, stale binary cache, race where old connserver still running reports wrong version, filesystem sync issues on a full disk.

Related errors

• error starting conn server: %w
• error starting conn server (after install): %w
• 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/e229e9622fbe1753. Report an issue: GitHub.