{"record":{"id":"ad2786ff66fe838e","repo":"wavetermdev/waveterm","slug":"unable-to-request-connection-domain-socket-v","errorCode":null,"errorMessage":"unable to request connection domain socket: %v","messagePattern":"unable to request connection domain socket: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/remote/conncontroller/conncontroller.go","lineNumber":287,"sourceCode":"\nfunc (conn *SSHConn) OpenDomainSocketListener(ctx context.Context) error {\n\tconn.Infof(ctx, \"running OpenDomainSocketListener...\\n\")\n\tallowed := WithLockRtn(conn, func() bool {\n\t\treturn conn.Status == Status_Connecting\n\t})\n\tif !allowed {\n\t\treturn fmt.Errorf(\"cannot open domain socket for %q when status is %q\", conn.GetName(), conn.GetStatus())\n\t}\n\tclient := conn.GetClient()\n\trandStr, err := utilfn.RandomHexString(16) // 64-bits of randomness\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error generating random string: %w\", err)\n\t}\n\tsockName := fmt.Sprintf(\"/tmp/waveterm-%s.sock\", randStr)\n\tconn.Infof(ctx, \"generated domain socket name %s\\n\", sockName)\n\tlistener, err := client.ListenUnix(sockName)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to request connection domain socket: %v\", err)\n\t}\n\tconn.WithLock(func() {\n\t\tconn.DomainSockName = sockName\n\t\tconn.DomainSockListener = listener\n\t})\n\tconn.Infof(ctx, \"successfully connected domain socket\\n\")\n\tgo func() {\n\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"conncontroller:OpenDomainSocketListener\", recover())\n\t\t}()\n\t\tdefer conn.WithLock(func() {\n\t\t\tconn.DomainSockListener = nil\n\t\t\tconn.DomainSockName = \"\"\n\t\t})\n\t\tmonitor := conn.GetMonitor()\n\t\tvar updateCallback func()\n\t\tif monitor != nil {\n\t\t\tupdateCallback = monitor.UpdateLastActivityTime","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/remote/conncontroller/conncontroller.go#L269-L305","documentation":"After generating a socket name, the code asks the SSH client (via the remote server) to create a Unix domain socket listener at /tmp/waveterm-<rand>.sock using ListenUnix. If the remote side cannot open it — bad path, permissions, path collision, or transport failure — the error is wrapped as 'unable to request connection domain socket'.","triggerScenarios":"client.ListenUnix(sockName) fails: the remote SSH server rejects the streamlocal forward, /tmp is not writable, the socket path already exists, or the SSH connection dropped.","commonSituations":"Remote host restricts Unix socket forwarding; stale /tmp/waveterm-*.sock files; sshd without streamlocal support; flaky SSH connection dying mid-setup; restricted containers/chroot jails.","solutions":["Verify the remote sshd permits Unix domain socket forwarding (streamlocal) and /tmp is writable","Remove stale /tmp/waveterm-*.sock files on the remote host","Check SSH connectivity/reconnect; a dropped connection will make ListenUnix fail","Confirm wsh is installed and up to date on the remote so the server side supports the socket request"],"exampleFix":"// before\nlistener, err := client.ListenUnix(sockName)\n// after (caller-side mitigation)\nlistener, err := client.ListenUnix(sockName)\nif err != nil {\n    // clean stale sockets and retry once\n    _ = client.CleanupStaleSockets(ctx)\n    listener, err = client.ListenUnix(sockName)\n}","handlingStrategy":"try-catch","validationCode":"// verify remote prerequisites before enabling wsh\nif conn.GetStatus() != remote.Status_Connected && conn.GetStatus() != remote.Status_Connecting {\n    return fmt.Errorf(\"ssh connection not ready\")\n}","typeGuard":null,"tryCatchPattern":"err := conn.OpenDomainSocketListener(ctx)\nif err != nil && strings.Contains(err.Error(), \"unable to request connection domain socket\") {\n    log.Printf(\"wsh domain socket failed: %v\", err)\n    // cleanup stale /tmp/waveterm-*.sock on remote and retry once\n}","preventionTips":["Confirm sshd supports Unix socket forwarding and /tmp is writable on the remote","Keep wsh installed and current on remote hosts","Clean stale wavertm sockets; monitor SSH connection stability"],"tags":["ssh","unix-socket","network","wsh"],"backgroundTag":"unix-socket-listen-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}