wavetermdev/waveterm · error

error installing wsh: %w

Error message

error installing wsh: %w

What it means

tryEnableWsh wraps a failure from InstallWsh() with this error. Installing/upgrading the wsh binary into the WSL distro (download + write into ~/.wsh) failed, so wsh remains unavailable and the result carries NoWshReason 'error installing wsh/connserver'.

Source

Thrown at pkg/wslconn/wslconn.go:621

	}
	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")
			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}
	}
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Check the wrapped error for download vs write failure details
2. Verify the distro has network access (or configure proxy) — wsh downloads the binary at install time
3. Free disk space / fix ~/.wsh ownership and permissions
4. Install wsh manually: download the release for the distro's os/arch and place it at ~/.wsh/bin/wsh
5. Retry the connection after fixing; the installer will re-run on needsInstall

Example fix

// before (fails offline)
err = conn.InstallWsh(ctx, osArchStr) // -> 'error installing wsh: download failed'
// after: pre-seed wsh inside the distro
// wsl -d Ubuntu -- bash -c 'mkdir -p ~/.wsh/bin && curl -fL <wsh-release-url> -o ~/.wsh/bin/wsh && chmod +x ~/.wsh/bin/wsh'

// verify outbound network from the distro before install
cmd := exec.Command("wsl", "-d", distro, "--", "bash", "-c", "curl -fsSI https://github.com >/dev/null")
if err := cmd.Run(); err != nil {
    return fmt.Errorf("distro has no network access; wsh install will fail")
}

err := conn.InstallWsh(ctx, osArch)
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) || strings.Contains(err.Error(), "download") {
        // network problem: pre-seed wsh manually or configure proxy
        return fmt.Errorf("wsh install failed (network?): pre-seed ~/.wsh/bin/wsh manually")
    }
    return err
}

When it happens

Trigger: InstallWsh fails after StartConnServer reported needsInstall — network download of the wsh release failed, the distro has no internet access, disk is full, or the install path is not writable.

Common situations: Corporate proxy/firewall blocking the release download, distro without outbound network, home directory quota exceeded, ~/.wsh owned by a different user.

Related errors

• SwapToken is required in CommandOptsType
• unable to obtain client info: %w
• error installing wsh to remote: %w
• ssh client is not connected, cannot install
• error copying wsh binary to remote: %w

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