{"record":{"id":"ad45f24aaa00629a","repo":"wavetermdev/waveterm","slug":"error-installing-wsh-w","errorCode":null,"errorMessage":"error installing wsh: %w","messagePattern":"error installing wsh: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":621,"sourceCode":"\t}\n\terr := conn.OpenDomainSocketListener(ctx)\n\tif err != nil {\n\t\tconn.Infof(ctx, \"ERROR opening domain socket listener: %v\\n\", err)\n\t\terr = fmt.Errorf(\"error opening domain socket listener: %w\", err)\n\t\treturn WshCheckResult{NoWshReason: \"error opening domain socket\", WshError: err}\n\t}\n\tneedsInstall, clientVersion, osArchStr, err := conn.StartConnServer(ctx, false)\n\tif err != nil {\n\t\tconn.Infof(ctx, \"ERROR starting conn server: %v\\n\", err)\n\t\terr = fmt.Errorf(\"error starting conn server: %w\", err)\n\t\treturn WshCheckResult{NoWshReason: \"error starting connserver\", WshError: err}\n\t}\n\tif needsInstall {\n\t\tconn.Infof(ctx, \"connserver needs to be (re)installed\\n\")\n\t\terr = conn.InstallWsh(ctx, osArchStr)\n\t\tif err != nil {\n\t\t\tconn.Infof(ctx, \"ERROR installing wsh: %v\\n\", err)\n\t\t\terr = fmt.Errorf(\"error installing wsh: %w\", err)\n\t\t\treturn WshCheckResult{NoWshReason: \"error installing wsh/connserver\", WshError: err}\n\t\t}\n\t\tneedsInstall, clientVersion, _, err = conn.StartConnServer(ctx, true)\n\t\tif err != nil {\n\t\t\tconn.Infof(ctx, \"ERROR starting conn server (after install): %v\\n\", err)\n\t\t\terr = fmt.Errorf(\"error starting conn server (after install): %w\", err)\n\t\t\treturn WshCheckResult{NoWshReason: \"error starting connserver\", WshError: err}\n\t\t}\n\t\tif needsInstall {\n\t\t\tconn.Infof(ctx, \"conn server not installed correctly (after install)\\n\")\n\t\t\terr = fmt.Errorf(\"conn server not installed correctly (after install)\")\n\t\t\treturn WshCheckResult{NoWshReason: \"connserver not installed properly\", WshError: err}\n\t\t}\n\t\treturn WshCheckResult{WshEnabled: true, ClientVersion: clientVersion}\n\t} else {\n\t\treturn WshCheckResult{WshEnabled: true, ClientVersion: clientVersion}\n\t}\n}","sourceCodeStart":603,"sourceCodeEnd":639,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L603-L639","documentation":"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'.","triggerScenarios":"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.","commonSituations":"Corporate proxy/firewall blocking the release download, distro without outbound network, home directory quota exceeded, ~/.wsh owned by a different user.","solutions":["Check the wrapped error for download vs write failure details","Verify the distro has network access (or configure proxy) — wsh downloads the binary at install time","Free disk space / fix ~/.wsh ownership and permissions","Install wsh manually: download the release for the distro's os/arch and place it at ~/.wsh/bin/wsh","Retry the connection after fixing; the installer will re-run on needsInstall"],"exampleFix":"// before (fails offline)\nerr = conn.InstallWsh(ctx, osArchStr) // -> 'error installing wsh: download failed'\n// after: pre-seed wsh inside the distro\n// wsl -d Ubuntu -- bash -c 'mkdir -p ~/.wsh/bin && curl -fL <wsh-release-url> -o ~/.wsh/bin/wsh && chmod +x ~/.wsh/bin/wsh'","handlingStrategy":"try-catch","validationCode":"// verify outbound network from the distro before install\ncmd := exec.Command(\"wsl\", \"-d\", distro, \"--\", \"bash\", \"-c\", \"curl -fsSI https://github.com >/dev/null\")\nif err := cmd.Run(); err != nil {\n    return fmt.Errorf(\"distro has no network access; wsh install will fail\")\n}","typeGuard":null,"tryCatchPattern":"err := conn.InstallWsh(ctx, osArch)\nif err != nil {\n    if errors.Is(err, context.DeadlineExceeded) || strings.Contains(err.Error(), \"download\") {\n        // network problem: pre-seed wsh manually or configure proxy\n        return fmt.Errorf(\"wsh install failed (network?): pre-seed ~/.wsh/bin/wsh manually\")\n    }\n    return err\n}","preventionTips":["Ensure distro has outbound network or a configured proxy","Keep disk space free in the distro","Pre-seed ~/.wsh/bin/wsh on offline machines","Match wsh binary arch to the distro"],"tags":["go","wsl","wsh","install","network"],"backgroundTag":"wsh-install-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}