{"record":{"id":"e378f3fceb52cf9b","repo":"wavetermdev/waveterm","slug":"error-extracting-socket-name-from-s-v","errorCode":null,"errorMessage":"error extracting socket name from %s: %v","messagePattern":"error extracting socket name from (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/waveapp/waveapp.go","lineNumber":177,"sourceCode":"}\n\nfunc (client *Client) Connect() error {\n\tjwtToken := os.Getenv(wshutil.WaveJwtTokenVarName)\n\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) {","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/waveapp/waveapp.go#L159-L195","documentation":"Wave app client connection fails when the JWT token passed to Connect cannot be parsed to extract the domain socket name. The token comes from the WAVE_JWT_TOKEN environment variable (wshutil.WaveJwtTokenVarName); ExtractUnverifiedSocketName decodes it (unverified, no signature check) to find the socket endpoint the client must dial. If the token is malformed, missing, or its payload lacks the socket-name field, Connect wraps the failure in this error and aborts startup.","triggerScenarios":"Calling Connect (via runMainE) when the WAVE_JWT_TOKEN env var is unset, truncated by shell quoting, contains an outdated token from a previous Wave session, or holds a JWT whose claims do not include the socket name key.","commonSituations":"Launching the waveapp binary outside a Wave Terminal block so the env var was never set; copy-pasting the token with trailing whitespace/newlines; token regenerated by Wave after the app was launched; older token format incompatible with the current wshutil parser.","solutions":["Verify the WAVE_JWT_TOKEN environment variable is set and non-empty before launching the app (echo it to confirm).","Re-launch the app from inside the Wave Terminal block so Wave injects a fresh token.","Check the token has no surrounding quotes, whitespace, or truncation (it should be three dot-separated base64 segments).","Upgrade Wave Terminal and the app together so ExtractUnverifiedSocketName and the token format match.","Print the underlying error (%v) to confirm whether it is a decode failure vs a missing claim."],"exampleFix":"// before (launching manually without token)\n./mywaveapp\n// after\nWAVE_JWT_TOKEN=\"$WAVE_JWT_TOKEN\" ./mywaveapp  # run inside the Wave block, or source the env Wave provides","handlingStrategy":"validation","validationCode":"token := os.Getenv(wshutil.WaveJwtTokenVarName)\nif token == \"\" {\n    return fmt.Errorf(\"%s is not set; launch the app from inside a Wave Terminal block\", wshutil.WaveJwtTokenVarName)\n}\nif strings.Count(token, \".\") != 2 {\n    return fmt.Errorf(\"%s does not look like a JWT (expected 3 dot-separated segments)\", wshutil.WaveJwtTokenVarName)\n}","typeGuard":"func hasValidJwtShape(token string) bool {\n    parts := strings.Split(strings.TrimSpace(token), \".\")\n    return len(parts) == 3 && parts[0] != \"\" && parts[1] != \"\"\n}","tryCatchPattern":null,"preventionTips":["Always launch waveapps from inside a Wave Terminal block so the JWT env var is injected.","Trim whitespace/quotes from the token before use.","Refresh the token whenever Wave Terminal restarts.","Log the underlying extraction error to distinguish decode failure from missing claims."],"tags":["jwt","ipc","domain-socket","startup"],"backgroundTag":"jwt-token-invalid","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}