wavetermdev/waveterm · error

error installing wsh to remote: %w

Error message

error installing wsh to remote: %w

What it means

UpdateWsh delegates the actual binary transfer to CpWshToRemote; if copying or installing wsh into the distro fails, the error is wrapped as 'error installing wsh to remote: %w'. The wrapped error carries the concrete cause (write failure, exec failure, arch mismatch, disk full, etc.).

Source

Thrown at pkg/wslconn/wslconn.go:373

var queryTextTemplate = strings.TrimSpace(`
Wave requires Wave Shell Extensions to be
installed on %q
to ensure a seamless experience.

Would you like to install them?
`)

func (conn *WslConn) UpdateWsh(ctx context.Context, clientDisplayName string, remoteInfo *wshrpc.RemoteInfo) error {
	conn.Infof(ctx, "attempting to update wsh for connection %s (os:%s arch:%s version:%s)\n",
		conn.GetName(), remoteInfo.ClientOs, remoteInfo.ClientArch, remoteInfo.ClientVersion)
	client := conn.GetClient()
	if client == nil {
		return fmt.Errorf("cannot update wsh: ssh client is not connected")
	}
	err := CpWshToRemote(ctx, client, remoteInfo.ClientOs, remoteInfo.ClientArch)
	if err != nil {
		return fmt.Errorf("error installing wsh to remote: %w", err)
	}
	conn.Infof(ctx, "successfully updated wsh on %s\n", conn.GetName())
	return nil

}

// returns (allowed, error)
func (conn *WslConn) getPermissionToInstallWsh(ctx context.Context, clientDisplayName string) (bool, error) {
	conn.Infof(ctx, "running getPermissionToInstallWsh...\n")
	queryText := fmt.Sprintf(queryTextTemplate, clientDisplayName)
	title := "Install Wave Shell Extensions"
	request := &userinput.UserInputRequest{
		ResponseType: "confirm",
		QueryText:    queryText,
		Title:        title,
		Markdown:     true,
		CheckBoxMsg:  "Automatically install for all connections",
		OkLabel:      "Install wsh",

View on GitHub (pinned to a4447c1563)

Solutions

1. Inspect the wrapped cause (%w) and fix it — e.g. free disk space or correct permissions on the wsh install path
2. Verify remoteInfo.ClientOs/ClientArch are correct and a matching wsh build exists
3. Reconnect the distro and retry the update; a stale client handle can cause remote exec failures
4. As a fallback, remove the existing wsh binary in the distro and let InstallWsh do a clean install

Example fix

// before: retrying blindly
err := conn.UpdateWsh(ctx, name, remoteInfo)
// after: log the root cause
if err := conn.UpdateWsh(ctx, name, remoteInfo); err != nil {
    log.Printf("wsh update failed: %v", errors.Unwrap(err))
    conn.Reconnect(ctx)
    err = conn.UpdateWsh(ctx, name, remoteInfo)
}

if err := conn.UpdateWsh(ctx, name, remoteInfo); err != nil {
    var cause error
    for errors.Unwrap(err) != nil {
        cause = errors.Unwrap(err)
    }
    log.Printf("wsh update root cause: %v", cause) // e.g. permission denied / no space left
}

When it happens

Trigger: Calling UpdateWsh when CpWshToRemote fails: the target binary path is not writable, the distro's filesystem is full, remoteInfo.ClientOs/ClientArch don't match an available wsh binary build, or executing remote commands via the wsl client errors.

Common situations: Updating wsh on a distro whose user lacks write permission to the install path; unusual os/arch combos with no matching binary; interrupted previous update leaving a locked/corrupt file; low disk space in the WSL virtual disk.

Related errors

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

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