{"record":{"id":"e95420692e7a3782","repo":"wavetermdev/waveterm","slug":"error-setting-up-connserver-rpc-client-v","errorCode":null,"errorMessage":"error setting up connserver rpc client: %v","messagePattern":"error setting up connserver rpc client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/wsh/cmd/wshcmd-connserver.go","lineNumber":241,"sourceCode":"\t\tdefer func() {\n\t\t\tpanichandler.PanicHandler(\"serverRunRouter:drainRawCh\", recover())\n\t\t}()\n\t\tdefer func() {\n\t\t\tlog.Printf(\"stdin closed, shutting down\")\n\t\t\twshutil.DoShutdown(\"\", 0, true)\n\t\t}()\n\t\tfor range rawCh {\n\t\t\t// ignore\n\t\t}\n\t}()\n\trouter.RegisterUpstream(termProxy)\n\n\tsockName := getRemoteDomainSocketName()\n\n\t// setup the connserver rpc client first\n\tclient, bareRouteId, err := setupConnServerRpcClientWithRouter(router, sockName)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error setting up connserver rpc client: %v\", err)\n\t}\n\twshfs.RpcClient = client\n\twshfs.RpcClientRouteId = bareRouteId\n\n\tlog.Printf(\"trying to get JWT public key\")\n\n\t// fetch and set JWT public key\n\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)","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/cmd/wsh/cmd/wshcmd-connserver.go#L223-L259","documentation":"Returned by serverRunRouter when setupConnServerRpcClientWithRouter fails to establish the RPC client to the connserver over the local domain socket. Without this client the router cannot proxy calls, so startup aborts. The underlying cause is wrapped with %v.","triggerScenarios":"The domain socket does not exist yet (connserver not started or crashed), permissions on the socket block connect, or the RPC handshake/route registration with the connserver fails.","commonSituations":"Starting `wsh server` before the connserver is up, stale socket file left behind by a crashed process, mismatched versions between wsh client and connserver, sandboxed environments restricting unix socket connections.","solutions":["Verify the connserver is running and the domain socket exists at getRemoteDomainSocketName()","Remove stale socket files and restart both the connserver and the router","Check socket file permissions (should be 0700 and owned by the same user)","Read the wrapped inner error for the exact handshake/connect failure and align wsh versions on both sides"],"exampleFix":"// before\nclient, bareRouteId, err := setupConnServerRpcClientWithRouter(router, sockName)\nif err != nil {\n    return fmt.Errorf(\"error setting up connserver rpc client: %v\", err)\n}\n// after\nclient, bareRouteId, err := setupConnServerRpcClientWithRouter(router, sockName)\nif err != nil {\n    if _, statErr := os.Stat(sockName); os.IsNotExist(statErr) {\n        return fmt.Errorf(\"connserver socket %s not found; is connserver running? underlying: %v\", sockName, err)\n    }\n    return fmt.Errorf(\"error setting up connserver rpc client: %v\", err)\n}","handlingStrategy":"retry","validationCode":"if _, err := os.Stat(sockName); err != nil {\n    return fmt.Errorf(\"connserver socket %s not available yet: %w\", sockName, err)\n}","typeGuard":null,"tryCatchPattern":"var client *wshclient.WshClient\nvar bareRouteId string\nvar err error\nfor i := 0; i < 5; i++ {\n    client, bareRouteId, err = setupConnServerRpcClientWithRouter(router, sockName)\n    if err == nil {\n        break\n    }\n    time.Sleep(1 << i * 100 * time.Millisecond)\n}\nif err != nil {\n    return fmt.Errorf(\"error setting up connserver rpc client: %v\", err)\n}","preventionTips":["Start the connserver before the router and add a readiness wait","Remove stale sockets from crashed prior runs","Keep wsh versions identical on both ends of the socket","Check socket permissions (0700, same user) in sandboxed environments"],"tags":["rpc","unix-socket","startup","connection"],"backgroundTag":"connection-refused","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}