{"record":{"id":"e9225cdbf630cce6","repo":"wavetermdev/waveterm","slug":"error-connecting-to-domain-socket-s-v","errorCode":null,"errorMessage":"error connecting to domain socket %s: %v","messagePattern":"error connecting to domain socket (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/wsh/cmd/wshcmd-connserver.go","lineNumber":301,"sourceCode":"\tstartJobLogCleanup()\n\tlog.Printf(\"running server, successfully started\")\n\tselect {}\n}\n\nfunc serverRunRouterDomainSocket(jwtToken string) error {\n\tlog.Printf(\"starting connserver router (domain socket upstream)\")\n\n\t// extract socket name from JWT token (unverified - we're on the client side)\n\tsockName, err := wshutil.ExtractUnverifiedSocketName(jwtToken)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error extracting socket name from JWT: %v\", err)\n\t}\n\n\t// connect to the forwarded domain socket\n\tsockName = wavebase.ExpandHomeDirSafe(sockName)\n\tconn, err := net.Dial(\"unix\", sockName)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error connecting to domain socket %s: %v\", sockName, err)\n\t}\n\n\t// create router\n\trouter := wshutil.NewWshRouter()\n\tConnServerWshRouter = router\n\n\t// create proxy for the domain socket connection\n\tupstreamProxy := wshutil.MakeRpcProxy(\"connserver-upstream\")\n\n\t// goroutine to write to the domain socket\n\tgo func() {\n\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"serverRunRouterDomainSocket:WriteLoop\", recover())\n\t\t}()\n\t\twriteErr := wshutil.AdaptOutputChToStream(upstreamProxy.ToRemoteCh, conn)\n\t\tif writeErr != nil {\n\t\t\tlog.Printf(\"error writing to upstream domain socket: %v\\n\", writeErr)\n\t\t}","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-connserver.go#L283-L319","documentation":"After extracting the socket name from the JWT, serverRunRouterDomainSocket dials the upstream unix domain socket with net.Dial(\"unix\", sockName). This error wraps that dial failure, meaning nothing is listening at the path, the socket file is stale, or the process lacks permission to connect.","triggerScenarios":"net.Dial(\"unix\", expandedSockName) fails inside serverRunRouterDomainSocket — e.g. the Wave server is not running, the socket was deleted, or permissions block access.","commonSituations":"Wave terminal server crashed leaving a dead socket file; connecting to a socket in another user's home (permission denied); WSL/network-mount filesystems where unix sockets don't work; typo'd or stale WAVETERM env vars pointing at an old session's socket.","solutions":["Confirm the Wave server is running and the socket file exists at the printed path (ls -l <sockName>).","Remove a stale socket file and restart the Wave server so it rebinds.","Check socket directory permissions (read/write/execute for your user).","Verify the socket path after ExpandHomeDirSafe points at the current session's socket, not a previous one.","If on WSL or a network mount, run the server and client on a filesystem supporting unix sockets."],"exampleFix":"// before\nsockName = wavebase.ExpandHomeDirSafe(sockName)\nconn, err := net.Dial(\"unix\", sockName)\nif err != nil {\n\treturn fmt.Errorf(\"error connecting to domain socket %s: %v\", sockName, err)\n}\n// after\nsockName = wavebase.ExpandHomeDirSafe(sockName)\nif fi, err := os.Stat(sockName); err != nil {\n\treturn fmt.Errorf(\"upstream socket %s does not exist (is the server running?): %w\", sockName, err)\n} else if fi.Mode()&os.ModeSocket == 0 {\n\treturn fmt.Errorf(\"path %s is not a socket (stale file); remove it and restart the server\", sockName)\n}\nconn, err := net.Dial(\"unix\", sockName)\nif err != nil {\n\treturn fmt.Errorf(\"error connecting to domain socket %s: %w\", sockName, err)\n}","handlingStrategy":"retry","validationCode":"sockName = wavebase.ExpandHomeDirSafe(sockName)\nif fi, err := os.Stat(sockName); err != nil {\n\treturn fmt.Errorf(\"socket %s missing: %w\", sockName, err)\n} else if fi.Mode()&os.ModeSocket == 0 {\n\treturn fmt.Errorf(\"%s is not a socket\", sockName)\n}","typeGuard":null,"tryCatchPattern":"conn, err := net.Dial(\"unix\", sockName)\nif err != nil {\n\treturn fmt.Errorf(\"error connecting to domain socket %s: %w\", sockName, err)\n}\ndefer conn.Close()","preventionTips":["Verify the Wave server is running before starting the connserver.","Remove stale socket files from crashed sessions.","Check directory permissions for your user.","Retry the dial briefly (with backoff) to absorb startup races.","Avoid sockets on WSL/network-mount filesystems."],"tags":["unix-socket","connection-refused","network","ipc"],"backgroundTag":"connection-refused","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}