{"record":{"id":"ec03e1cf49978976","repo":"wavetermdev/waveterm","slug":"error-authenticating-rpc-connection-v","errorCode":null,"errorMessage":"error authenticating rpc connection: %v","messagePattern":"error authenticating rpc connection: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/waveapp/waveapp.go","lineNumber":186,"sourceCode":"\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 {\n\tblockORef, err := wshclient.VDomCreateContextCommand(\n\t\tc.RpcClient,\n\t\tvdom.VDomCreateContext{Target: target},\n\t\t&wshrpc.RpcOpts{Route: wshutil.MakeFeBlockRouteId(c.RpcContext.BlockId)},\n\t)","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/waveapp/waveapp.go#L168-L204","documentation":"The RPC transport is up, but the AuthenticateCommand RPC sent over the ControlRoute failed. Wave requires the client to prove its identity by presenting the JWT before any further RPCs are honored. Failures here indicate the server rejected the call (invalid/expired token), the response never arrived (timeout), or routing to the control endpoint failed.","triggerScenarios":"Calling Connect when the JWT token has expired or was revoked, the control route is unreachable, the Wave host rejects the handshake, or the RPC times out because the Wave process is unresponsive.","commonSituations":"Long-running environments where the token TTL expired; system clock skew invalidating token timestamps; Wave busy/hung so the authentication response never returns; version mismatch where the server no longer accepts the client's auth payload shape.","solutions":["Relaunch the app from a fresh Wave block to obtain a new JWT token and retry.","Check clock synchronization on the host (token expiry is time-based).","Confirm the Wave Terminal version matches the waveapp/wsh client libraries.","Retry after verifying Wave is responsive (other wsh commands work in the block).","Inspect the wrapped %v error for 'timeout' vs explicit rejection to pick between retry and re-auth."],"exampleFix":"// before: single auth attempt with stale token\nauthRtnData, err := wshclient.AuthenticateCommand(client.RpcClient, jwtToken, &wshrpc.RpcOpts{Route: wshutil.ControlRoute})\n// after: retry transient failures\nvar authRtnData *wshrpc.AuthRtnData\nfor i := 0; i < 3; i++ {\n    authRtnData, err = wshclient.AuthenticateCommand(client.RpcClient, jwtToken, &wshrpc.RpcOpts{Route: wshutil.ControlRoute})\n    if err == nil { break }\n    time.Sleep(time.Second)\n}","handlingStrategy":"retry","validationCode":"if jwtToken == \"\" {\n    return fmt.Errorf(\"cannot authenticate: empty JWT token\")\n}\n// ensure host clock is sane if tokens carry expiry claims","typeGuard":null,"tryCatchPattern":"authRtnData, err := wshclient.AuthenticateCommand(client.RpcClient, jwtToken, &wshrpc.RpcOpts{Route: wshutil.ControlRoute})\nif err != nil {\n    if strings.Contains(err.Error(), \"timeout\") {\n        // transient: retry once with fresh client\n    }\n    return fmt.Errorf(\"error authenticating rpc connection: %v\", err)\n}","preventionTips":["Obtain the token fresh at each launch; JWTs expire.","Keep host clocks synchronized (NTP).","Keep Wave Terminal and wsh/waveapp library versions aligned.","Retry transient timeouts; treat explicit rejection as requiring a new token."],"tags":["authentication","jwt","rpc","timeout"],"backgroundTag":"rpc-authentication-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}