wavetermdev/waveterm · error

error copying wsh binary to remote: %w

Error message

error copying wsh binary to remote: %w

What it means

InstallWsh copies the wsh binary into the distro via CpWshToRemote; on failure the cause is wrapped as 'error copying wsh binary to remote: %w'. This fires after platform detection (GetClientPlatform/GetClientPlatformFromOsArchStr), so it reflects a failure in the actual transfer or remote install step, not detection.

Source

Thrown at pkg/wslconn/wslconn.go:446

	if client == nil {
		conn.Infof(ctx, "ERROR ssh client is not connected, cannot install\n")
		return fmt.Errorf("ssh client is not connected, cannot install")
	}
	var clientOs, clientArch string
	var err error
	if osArchStr != "" {
		clientOs, clientArch, err = GetClientPlatformFromOsArchStr(ctx, osArchStr)
	} else {
		clientOs, clientArch, err = GetClientPlatform(ctx, genconn.MakeWSLShellClient(client))
	}
	if err != nil {
		conn.Infof(ctx, "ERROR detecting client platform: %v\n", err)
	}
	conn.Infof(ctx, "detected remote platform os:%s arch:%s\n", clientOs, clientArch)
	err = CpWshToRemote(ctx, client, clientOs, clientArch)
	if err != nil {
		conn.Infof(ctx, "ERROR copying wsh binary to remote: %v\n", err)
		return fmt.Errorf("error copying wsh binary to remote: %w", err)
	}
	conn.Infof(ctx, "successfully installed wsh\n")
	return nil
}

func (conn *WslConn) GetClient() *wsl.Distro {
	conn.Lock.Lock()
	defer conn.Lock.Unlock()
	return conn.Client
}

func (conn *WslConn) Reconnect(ctx context.Context) error {
	err := conn.Close()
	if err != nil {
		return err
	}
	return conn.Connect(ctx)
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the wrapped cause (%w) — fix permissions or free space on the distro's wsh install path
2. Verify the detected os/arch (logged as 'detected remote platform os:... arch:...') has a matching wsh binary
3. Reconnect the distro and retry InstallWsh
4. Manually verify inside the distro that the wsh binary path exists and is executable after a partial install, then retry

Example fix

// before: silent partial install
err := conn.InstallWsh(ctx, osArchStr)
// after
if err := conn.InstallWsh(ctx, osArchStr); err != nil {
    log.Printf("install failed, root cause: %v", errors.Unwrap(err))
    return err
}

if err := conn.InstallWsh(ctx, osArchStr); err != nil {
    if strings.Contains(err.Error(), "error copying wsh binary to remote") {
        log.Printf("wsh copy failed: %v", errors.Unwrap(err))
        // fix permissions/disk, reconnect, retry once
        _ = conn.Reconnect(ctx)
        err = conn.InstallWsh(ctx, osArchStr)
    }
}

When it happens

Trigger: Calling InstallWsh when CpWshToRemote fails: unwritable install path in the distro, no wsh build matching the detected clientOs/clientArch, disk full, or the remote command execution errors.

Common situations: First-time wsh install on a distro where the target user can't write to the install location; exotic WSL distros (e.g. non-Ubuntu with unusual layout); WSL virtual disk out of space; corrupted download of the wsh artifact.

Related errors

• error installing wsh 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/68a519bec6686a79. Report an issue: GitHub.