wavetermdev/waveterm · error

error extracting socket name from %s: %v

Error message

error extracting socket name from %s: %v

What it means

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.

Source

Thrown at pkg/waveapp/waveapp.go:177

}

func (client *Client) Connect() error {
	jwtToken := os.Getenv(wshutil.WaveJwtTokenVarName)
	if jwtToken == "" {
		return fmt.Errorf("no %s env var set", wshutil.WaveJwtTokenVarName)
	}
	rpcCtx, err := wshutil.ExtractUnverifiedRpcContext(jwtToken)
	if err != nil {
		return fmt.Errorf("error extracting rpc context from %s: %v", wshutil.WaveJwtTokenVarName, err)
	}
	client.RpcContext = rpcCtx
	if client.RpcContext == nil || client.RpcContext.BlockId == "" {
		return fmt.Errorf("no block id in rpc context")
	}
	client.ServerImpl = &WaveAppServerImpl{BlockId: client.RpcContext.BlockId, Client: client}
	sockName, err := wshutil.ExtractUnverifiedSocketName(jwtToken)
	if err != nil {
		return fmt.Errorf("error extracting socket name from %s: %v", wshutil.WaveJwtTokenVarName, err)
	}
	rpcClient, err := wshutil.SetupDomainSocketRpcClient(sockName, client.ServerImpl, "vdomclient")
	if err != nil {
		return fmt.Errorf("error setting up domain socket rpc client: %v", err)
	}
	client.RpcClient = rpcClient
	authRtnData, err := wshclient.AuthenticateCommand(client.RpcClient, jwtToken, &wshrpc.RpcOpts{Route: wshutil.ControlRoute})
	if err != nil {
		return fmt.Errorf("error authenticating rpc connection: %v", err)
	}
	if authRtnData.RouteId == "" {
		return fmt.Errorf("authentication returned empty routeid")
	}
	client.RouteId = authRtnData.RouteId
	return nil
}

func (c *Client) SetRootElem(elem *vdom.VDomElem) {

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the WAVE_JWT_TOKEN environment variable is set and non-empty before launching the app (echo it to confirm).
2. Re-launch the app from inside the Wave Terminal block so Wave injects a fresh token.
3. Check the token has no surrounding quotes, whitespace, or truncation (it should be three dot-separated base64 segments).
4. Upgrade Wave Terminal and the app together so ExtractUnverifiedSocketName and the token format match.
5. Print the underlying error (%v) to confirm whether it is a decode failure vs a missing claim.

Example fix

// before (launching manually without token)
./mywaveapp
// after
WAVE_JWT_TOKEN="$WAVE_JWT_TOKEN" ./mywaveapp  # run inside the Wave block, or source the env Wave provides

token := os.Getenv(wshutil.WaveJwtTokenVarName)
if token == "" {
    return fmt.Errorf("%s is not set; launch the app from inside a Wave Terminal block", wshutil.WaveJwtTokenVarName)
}
if strings.Count(token, ".") != 2 {
    return fmt.Errorf("%s does not look like a JWT (expected 3 dot-separated segments)", wshutil.WaveJwtTokenVarName)
}

func hasValidJwtShape(token string) bool {
    parts := strings.Split(strings.TrimSpace(token), ".")
    return len(parts) == 3 && parts[0] != "" && parts[1] != ""
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• error getting jwt public key: %v
• error decoding jwt public key: %v
• error setting up domain socket rpc client: %v
• error generating jwt keypair: %w
• window ${windowId} not found

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/e378f3fceb52cf9b. Report an issue: GitHub.