{"record":{"id":"a2d9982f2f407750","repo":"wavetermdev/waveterm","slug":"error-starting-conn-server-w","errorCode":null,"errorMessage":"error starting conn server: %w","messagePattern":"error starting conn server: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":613,"sourceCode":"\t\tallowInstall, err := conn.getPermissionToInstallWsh(ctx, clientDisplayName)\n\t\tif err != nil {\n\t\t\tlog.Printf(\"error getting permission to install wsh: %v\\n\", err)\n\t\t\treturn WshCheckResult{NoWshReason: \"error getting user permission to install\", WshError: err}\n\t\t}\n\t\tif !allowInstall {\n\t\t\treturn WshCheckResult{NoWshReason: \"user selected not to install wsh extensions\"}\n\t\t}\n\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\")","sourceCodeStart":595,"sourceCodeEnd":631,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L595-L631","documentation":"tryEnableWsh wraps a failure from StartConnServer(ctx, false) with this error. The connserver (wsh server) process inside the WSL distro failed to start or respond on the first attempt, so wsh setup aborts with NoWshReason 'error starting connserver'.","triggerScenarios":"StartConnServer fails on the initial probe — the wsh binary is missing or incompatible in the distro, the RPC handshake times out, or the domain socket exists but no server answers.","commonSituations":"wsh was never installed in a fresh distro, wsh version too old for the client, distro's shell init scripts hang so the server never starts, distro is suspended mid-startup.","solutions":["Read the wrapped underlying error to distinguish timeout vs missing binary","Ensure wsh is installed in the distro: run 'wsh install' or let InstallWsh retry (the code does this only when needsInstall=true)","Update wsh in the distro ('wsh upgrade') to match the Wave client version","Check for slow/hanging shell rc files inside the distro that delay server startup","Restart the distro (wsl --shutdown) and reconnect"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure distro is up and wsh binary present before connecting\nif err := exec.Command(\"wsl\", \"-d\", distro, \"--\", \"bash\", \"-c\", \"echo ok\").Run(); err != nil {\n    return fmt.Errorf(\"distro not starting: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"res, err := tryEnableWsh(ctx, conn)\nif err != nil && strings.Contains(err.Error(), \"error starting conn server\") {\n    // retry after a short wait; slow distros often just need time\n    time.Sleep(3 * time.Second)\n    res, err = tryEnableWsh(ctx, conn)\n}","preventionTips":["Wait for full distro boot before connecting","Remove slow/hanging rc files from distro shell init","Keep wsh versions in sync with Wave client","Use 'wsl --shutdown' to clear stuck distros before retrying"],"tags":["go","wsl","wsh","connserver","rpc"],"backgroundTag":"connserver-start-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}