{"record":{"id":"72054231c10013fd","repo":"wavetermdev/waveterm","slug":"error-setting-up-domain-socket-rpc-client-v","errorCode":null,"errorMessage":"error setting up domain socket rpc client: %v","messagePattern":"error setting up domain socket rpc client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/waveapp/waveapp.go","lineNumber":181,"sourceCode":"\tif jwtToken == \"\" {\n\t\treturn fmt.Errorf(\"no %s env var set\", wshutil.WaveJwtTokenVarName)\n\t}\n\trpcCtx, err := wshutil.ExtractUnverifiedRpcContext(jwtToken)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error extracting rpc context from %s: %v\", wshutil.WaveJwtTokenVarName, err)\n\t}\n\tclient.RpcContext = rpcCtx\n\tif client.RpcContext == nil || client.RpcContext.BlockId == \"\" {\n\t\treturn fmt.Errorf(\"no block id in rpc context\")\n\t}\n\tclient.ServerImpl = &WaveAppServerImpl{BlockId: client.RpcContext.BlockId, Client: client}\n\tsockName, err := wshutil.ExtractUnverifiedSocketName(jwtToken)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error extracting socket name from %s: %v\", wshutil.WaveJwtTokenVarName, err)\n\t}\n\trpcClient, err := wshutil.SetupDomainSocketRpcClient(sockName, client.ServerImpl, \"vdomclient\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error setting up domain socket rpc client: %v\", err)\n\t}\n\tclient.RpcClient = rpcClient\n\tauthRtnData, err := wshclient.AuthenticateCommand(client.RpcClient, jwtToken, &wshrpc.RpcOpts{Route: wshutil.ControlRoute})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error authenticating rpc connection: %v\", err)\n\t}\n\tif authRtnData.RouteId == \"\" {\n\t\treturn fmt.Errorf(\"authentication returned empty routeid\")\n\t}\n\tclient.RouteId = authRtnData.RouteId\n\treturn nil\n}\n\nfunc (c *Client) SetRootElem(elem *vdom.VDomElem) {\n\tc.RootElem = elem\n}\n\nfunc (c *Client) CreateVDomContext(target *vdom.VDomTarget) error {","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/waveapp/waveapp.go#L163-L199","documentation":"After extracting the socket name from the JWT, Connect calls wshutil.SetupDomainSocketRpcClient to dial the Wave Terminal domain socket and establish the wsh RPC channel. This error wraps any failure in that setup: the socket file not existing, permission denied, connection refused, or protocol/handshake problems. It means the vdom client could not establish its IPC transport to the Wave Terminal host process.","triggerScenarios":"Calling Connect when the Wave domain socket has been deleted (Wave restarted or exited), the socket path from the token points to a different machine/container, file permissions on ~/.waveterm deny access, or the socket listener in Wave is not running.","commonSituations":"Wave Terminal restarted while the app process kept the old token/socket; running the app inside a container without the socket mounted; user mismatch (socket owned by another user); stale WAVE_JWT_TOKEN after a Wave upgrade changed socket naming.","solutions":["Confirm Wave Terminal is running and the block that spawned the app is still open.","Restart the app from a fresh Wave block so it gets a current token and socket path.","Check the socket file exists at the path encoded in the token and is accessible (ls -l, permissions).","If in a container/VM, mount or forward the Wave domain socket into the environment.","Read the wrapped %v error to distinguish not-found vs permission-denied vs handshake failure."],"exampleFix":"// before: app outlives Wave restart\n// (old token reused, socket gone)\n// after: detect stale connection and relaunch from a live block\nif _, err := os.Stat(sockPath); err != nil { log.Fatal(\"wave socket unavailable, relaunch app from Wave block\") }","handlingStrategy":"retry","validationCode":"if _, err := os.Stat(sockName); err != nil {\n    return fmt.Errorf(\"wave domain socket %q unavailable: %w (is Wave Terminal running?)\", sockName, err)\n}","typeGuard":null,"tryCatchPattern":"rpcClient, err := wshutil.SetupDomainSocketRpcClient(sockName, serverImpl, \"vdomclient\")\nif err != nil {\n    return fmt.Errorf(\"error setting up domain socket rpc client: %v\", err)\n}","preventionTips":["Confirm Wave Terminal is running before starting the app.","Restart the app after Wave restarts; never reuse tokens from a previous session.","Mount/forward the Wave domain socket when running in containers.","Check socket file permissions match the user running the app."],"tags":["ipc","domain-socket","network","connection"],"backgroundTag":"domain-socket-connect-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}