{"record":{"id":"61301a2004474fb6","repo":"wavetermdev/waveterm","slug":"cannot-create-unix-listener-v","errorCode":null,"errorMessage":"cannot create unix listener: %v","messagePattern":"cannot create unix listener: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/wsh/cmd/wshcmd-connserver.go","lineNumber":267,"sourceCode":"\tjwtPublicKeyB64, err := wshclient.GetJwtPublicKeyCommand(client, nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error getting jwt public key: %v\", err)\n\t}\n\tjwtPublicKeyBytes, err := base64.StdEncoding.DecodeString(jwtPublicKeyB64)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error decoding jwt public key: %v\", err)\n\t}\n\terr = wavejwt.SetPublicKey(jwtPublicKeyBytes)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error setting jwt public key: %v\", err)\n\t}\n\n\tlog.Printf(\"got JWT public key\")\n\n\t// now set up the domain socket\n\tunixListener, err := MakeRemoteUnixListener()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot create unix listener: %v\", err)\n\t}\n\tlog.Printf(\"unix listener started\")\n\tgo func() {\n\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"serverRunRouter:runListener\", recover())\n\t\t}()\n\t\trunListener(unixListener, router)\n\t}()\n\t// run the sysinfo loop\n\tgo func() {\n\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"serverRunRouter:RunSysInfoLoop\", recover())\n\t\t}()\n\t\twshremote.RunSysInfoLoop(client, connServerConnName)\n\t}()\n\tstartJobLogCleanup()\n\tlog.Printf(\"running server, successfully started\")\n\tselect {}","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-connserver.go#L249-L285","documentation":"serverRunRouter wraps the error from MakeRemoteUnixListener, which creates the local unix domain socket that wsh clients connect to. Failure means the socket path could not be created/bound — typically a stale socket file, permission problems, or a path that is too long or on an unsuitable filesystem. Without this listener no local wsh commands can reach the connserver.","triggerScenarios":"serverRunRouter calls MakeRemoteUnixListener() after setting the JWT public key; the underlying net.Listen(\"unix\", path) fails.","commonSituations":"Leftover socket file from a previous crashed run; running in a container/home dir with wrong permissions; TMPDIR pointing to a nonexistent or full path; filesystem that does not support unix sockets (some network mounts).","solutions":["Remove any stale socket file at the path MakeRemoteUnixListener uses, then retry.","Verify the parent directory exists and is writable by the current user.","Check TMPDIR/env overrides and socket path length (< ~104 chars on macOS).","Confirm the filesystem supports unix sockets; move the socket dir if on a network mount.","Check the wrapped %v for 'address already in use' vs 'permission denied' to target the fix."],"exampleFix":"// before\nunixListener, err := MakeRemoteUnixListener()\nif err != nil {\n\treturn fmt.Errorf(\"cannot create unix listener: %v\", err)\n}\n// after\nsockPath := getRemoteDomainSocketName()\nif fi, err := os.Stat(sockPath); err == nil && fi.Mode()&os.ModeSocket != 0 {\n\tos.Remove(sockPath) // clear stale socket from a previous run\n}\nunixListener, err := MakeRemoteUnixListener()\nif err != nil {\n\treturn fmt.Errorf(\"cannot create unix listener %s: %w\", sockPath, err)\n}","handlingStrategy":"try-catch","validationCode":"sockPath := getRemoteDomainSocketName()\nif fi, err := os.Stat(sockPath); err == nil && fi.Mode()&os.ModeSocket != 0 {\n\tos.Remove(sockPath)\n}\nif err := os.MkdirAll(filepath.Dir(sockPath), 0o700); err != nil {\n\treturn err\n}","typeGuard":null,"tryCatchPattern":"unixListener, err := MakeRemoteUnixListener()\nif err != nil {\n\treturn fmt.Errorf(\"cannot create unix listener: %w\", err)\n}\ndefer unixListener.Close()","preventionTips":["Clean up socket files on shutdown (defer os.Remove).","Run connserver with a writable, local (non-NFS) socket directory.","Keep socket paths short.","Check for an already-running instance before binding."],"tags":["unix-socket","network","filesystem","ipc"],"backgroundTag":"unix-socket-bind-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}