{"record":{"id":"b505586a0b9841d2","repo":"wavetermdev/waveterm","slug":"error-opening-domain-socket-listener-w","errorCode":null,"errorMessage":"error opening domain socket listener: %w","messagePattern":"error opening domain socket listener: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/wslconn/wslconn.go","lineNumber":607,"sourceCode":"\tenableWsh, askBeforeInstall := conn.getConnWshSettings()\n\tconn.Infof(ctx, \"wsh settings enable:%v ask:%v\\n\", enableWsh, askBeforeInstall)\n\tif !enableWsh {\n\t\treturn WshCheckResult{NoWshReason: \"conn:wshenabled set to false\"}\n\t}\n\tif askBeforeInstall {\n\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 {","sourceCodeStart":589,"sourceCodeEnd":625,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wslconn/wslconn.go#L589-L625","documentation":"tryEnableWsh wraps any failure from OpenDomainSocketListener() with this error. It means the Unix-domain socket listener for the wsh connserver inside the WSL distro could not be created, so wsh extension setup is aborted and the connection reports a NoWshReason of 'error opening domain socket'.","triggerScenarios":"OpenDomainSocketListener fails during connectInternal — typically because the ~/.wsh directory/socket path cannot be created in the distro, the socket already exists from a stale run, or the distro's filesystem/permissions block socket creation.","commonSituations":"Read-only or full WSL filesystem, stale socket file from a previous crashed session, WSL distro not fully booted, mismatched user permissions after changing WSL user.","solutions":["Inspect the wrapped error (%w) to find the underlying syscall failure (mkdir, bind, chmod)","Remove stale socket files in ~/.wsh inside the WSL distro and reconnect","Verify the distro's filesystem is writable and the user owns their home directory","Fully restart the WSL distro (wsl --shutdown) to clear stale state","Update wsh: run 'wsh upgrade' inside the distro"],"exampleFix":"// before\nres, err := wshrpc.DoWshEnableCommand(connName) // surfaces 'error opening domain socket listener: ...'\n// after\n// run inside distro first: rm -f ~/.wsh/*.sock && wsl --shutdown\nres, err := wshrpc.DoWshEnableCommand(connName)","handlingStrategy":"try-catch","validationCode":"// check distro is reachable and home is writable first\nif err := exec.Command(\"wsl\", \"-d\", distro, \"--\", \"bash\", \"-c\", \"touch ~/.wsh_probe && rm ~/.wsh_probe\").Run(); err != nil {\n    return fmt.Errorf(\"distro home not writable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"res, err := tryEnableWsh(ctx, conn)\nif err != nil && errors.Is(err, baseErr) && strings.Contains(err.Error(), \"domain socket listener\") {\n    // clean stale sockets then retry once\n    exec.Command(\"wsl\", \"-d\", distro, \"--\", \"bash\", \"-c\", \"rm -f ~/.wsh/*.sock\").Run()\n    res, err = tryEnableWsh(ctx, conn)\n}","preventionTips":["Periodically clean stale sockets in ~/.wsh","Run 'wsl --shutdown' after abnormal exits","Keep distro home directory writable and un-quota'd","Keep wsh upgraded to match the client"],"tags":["go","domain-socket","wsl","wsh","filesystem"],"backgroundTag":"domain-socket-bind-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}