wavetermdev/waveterm · error

error checking wsh version: %w

Error message

error checking wsh version: %w

What it means

StartConnServer launched the wsh connserver inside the WSL distro and read its first stdout line (the version string). That version line was then passed to conncontroller.IsWshVersionUpToDate, which failed to parse it or to compare it against the local wsh version. The error wraps the underlying cause, so the real problem is usually a malformed or empty version line rather than a connection failure.

Source

Thrown at pkg/wslconn/wslconn.go:298

	cmd.SetStderr(pipeWrite)
	cmd.SetStdin(inputPipeRead)
	log.Printf("starting conn controller: %q\n", cmdStr)
	blocklogger.Debugf(ctx, "[conndebug] wrapped command:\n%s\n", shWrappedCmdStr)
	err := cmd.Start()
	if err != nil {
		return false, "", "", fmt.Errorf("unable to start conn controller cmd: %w", err)
	}
	linesChan := utilfn.StreamToLinesChan(pipeRead)
	versionLine, err := utilfn.ReadLineWithTimeout(linesChan, 30*time.Second)
	if err != nil {
		cancelFn()
		return false, "", "", fmt.Errorf("error reading wsh version: %w", err)
	}
	conn.Infof(ctx, "got connserver version: %s\n", strings.TrimSpace(versionLine))
	isUpToDate, clientVersion, osArchStr, err := conncontroller.IsWshVersionUpToDate(ctx, versionLine)
	if err != nil {
		cancelFn()
		return false, "", "", fmt.Errorf("error checking wsh version: %w", err)
	}
	if isUpToDate && !afterUpdate && os.Getenv(wavebase.WaveWshForceUpdateVarName) != "" {
		isUpToDate = false
		conn.Infof(ctx, "%s set, forcing wsh update\n", wavebase.WaveWshForceUpdateVarName)
	}
	conn.Infof(ctx, "connserver up-to-date: %v\n", isUpToDate)
	if !isUpToDate {
		cancelFn()
		return true, clientVersion, osArchStr, nil
	}
	conn.WithLock(func() {
		conn.ConnController = cmd
	})
	// service the I/O
	go func() {
		defer func() {
			panichandler.PanicHandler("wslconn:cmd.Wait", recover())
		}()

View on GitHub (pinned to a4447c1563)

Solutions

1. Reinstall/update wsh in the distro so the version line is current and well-formed (WslConn.InstallWsh or UpdateWsh, or run the update from the Wave UI)
2. Check the distro's shell profiles (.bashrc/.profile) for output on non-interactive shells and silence it
3. Verify the wsh binary is the official one: run 'wsh version' manually inside the distro and check the output format
4. Read the wrapped error (%w) for the concrete parse failure and match it against your wsh version

Example fix

// before: connserver emits banner text before version
// .bashrc: echo "Welcome to my distro"
// after
// .bashrc: [[ $- == *i* ]] && echo "Welcome to my distro"  # only for interactive shells

// verify wsh in the distro emits a clean version line before starting the connserver
out, err := exec.Command("wsl", "-d", distroName, "--", wshPath, "version").Output()
if err != nil || !regexp.MustCompile(`^\d+\.\d+\.\d+`).Match(bytes.TrimSpace(out)) {
    // wsh missing or output polluted — reinstall before StartConnServer
}

if _, _, _, err := conn.StartConnServer(ctx, false); err != nil {
    if strings.Contains(err.Error(), "error checking wsh version") {
        // reinstall wsh, silence shell banners, then retry
        _ = conn.InstallWsh(ctx, "")
        _, _, _, err = conn.StartConnServer(ctx, false)
    }
}

When it happens

Trigger: Calling WslConn.StartConnServer (via tryEnableWsh) when the remote wsh binary emits an unparseable first stdout line: a corrupted/hand-edited wsh binary, a shell profile printing banner text before the version, a non-English locale altering output, or a version string from a much older/newer wsh that the parser rejects.

Common situations: Users with shell rc files that echo text on non-interactive shells; stale wsh binaries from an interrupted earlier update; custom wsh builds whose version doesn't match the expected semver format; WSL distros where PATH resolves a different wsh than the one Wave installed.

Related errors

• timeout waiting for connserver to register
• error starting conn server: %w
• error starting conn server (after install): %w
• conn server not installed correctly (after install)
• encryption is not available

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