{"record":{"id":"5264270d6804c74c","repo":"wavetermdev/waveterm","slug":"error-installing-wsh-to-remote-w-526427","errorCode":null,"errorMessage":"error installing wsh to remote: %w","messagePattern":"error installing wsh to remote: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":373,"sourceCode":"\nvar queryTextTemplate = strings.TrimSpace(`\nWave requires Wave Shell Extensions to be\ninstalled on %q\nto ensure a seamless experience.\n\nWould you like to install them?\n`)\n\nfunc (conn *WslConn) UpdateWsh(ctx context.Context, clientDisplayName string, remoteInfo *wshrpc.RemoteInfo) error {\n\tconn.Infof(ctx, \"attempting to update wsh for connection %s (os:%s arch:%s version:%s)\\n\",\n\t\tconn.GetName(), remoteInfo.ClientOs, remoteInfo.ClientArch, remoteInfo.ClientVersion)\n\tclient := conn.GetClient()\n\tif client == nil {\n\t\treturn fmt.Errorf(\"cannot update wsh: ssh client is not connected\")\n\t}\n\terr := CpWshToRemote(ctx, client, remoteInfo.ClientOs, remoteInfo.ClientArch)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error installing wsh to remote: %w\", err)\n\t}\n\tconn.Infof(ctx, \"successfully updated wsh on %s\\n\", conn.GetName())\n\treturn nil\n\n}\n\n// returns (allowed, error)\nfunc (conn *WslConn) getPermissionToInstallWsh(ctx context.Context, clientDisplayName string) (bool, error) {\n\tconn.Infof(ctx, \"running getPermissionToInstallWsh...\\n\")\n\tqueryText := fmt.Sprintf(queryTextTemplate, clientDisplayName)\n\ttitle := \"Install Wave Shell Extensions\"\n\trequest := &userinput.UserInputRequest{\n\t\tResponseType: \"confirm\",\n\t\tQueryText:    queryText,\n\t\tTitle:        title,\n\t\tMarkdown:     true,\n\t\tCheckBoxMsg:  \"Automatically install for all connections\",\n\t\tOkLabel:      \"Install wsh\",","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L355-L391","documentation":"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.).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped cause (%w) and fix it — e.g. free disk space or correct permissions on the wsh install path","Verify remoteInfo.ClientOs/ClientArch are correct and a matching wsh build exists","Reconnect the distro and retry the update; a stale client handle can cause remote exec failures","As a fallback, remove the existing wsh binary in the distro and let InstallWsh do a clean install"],"exampleFix":"// before: retrying blindly\nerr := conn.UpdateWsh(ctx, name, remoteInfo)\n// after: log the root cause\nif err := conn.UpdateWsh(ctx, name, remoteInfo); err != nil {\n    log.Printf(\"wsh update failed: %v\", errors.Unwrap(err))\n    conn.Reconnect(ctx)\n    err = conn.UpdateWsh(ctx, name, remoteInfo)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := conn.UpdateWsh(ctx, name, remoteInfo); err != nil {\n    var cause error\n    for errors.Unwrap(err) != nil {\n        cause = errors.Unwrap(err)\n    }\n    log.Printf(\"wsh update root cause: %v\", cause) // e.g. permission denied / no space left\n}","preventionTips":["Ensure the distro user can write to the wsh install path","Keep free disk space in the WSL virtual disk","Pass accurate ClientOs/ClientArch in RemoteInfo","Reconnect before retrying after a failed update"],"tags":["wsl","wsh","install","copy-failed"],"backgroundTag":"remote-binary-install-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}