wavetermdev/waveterm · error

vdom context route could not be established

Error message

vdom context route could not be established

What it means

The WaitForRouteCommand RPC completed without error but reported gotRoute == false: the frontend block route (MakeFeBlockRouteId of the vdom context block) did not appear within the 4000ms wait window. This means Wave's frontend never started listening on the block route, so RPCs targeted at the vdom context would have nowhere to go.

Source

Thrown at pkg/waveapp/waveapp.go:218

	blockORef, err := wshclient.VDomCreateContextCommand(
		c.RpcClient,
		vdom.VDomCreateContext{Target: target},
		&wshrpc.RpcOpts{Route: wshutil.MakeFeBlockRouteId(c.RpcContext.BlockId)},
	)
	if err != nil {
		return err
	}
	c.VDomContextBlockId = blockORef.OID
	log.Printf("created vdom context: %v\n", blockORef)
	gotRoute, err := wshclient.WaitForRouteCommand(c.RpcClient, wshrpc.CommandWaitForRouteData{
		RouteId: wshutil.MakeFeBlockRouteId(blockORef.OID),
		WaitMs:  4000,
	}, &wshrpc.RpcOpts{Timeout: 5000})
	if err != nil {
		return fmt.Errorf("error waiting for vdom context route: %v", err)
	}
	if !gotRoute {
		return fmt.Errorf("vdom context route could not be established")
	}
	wshclient.EventSubCommand(c.RpcClient, wps.SubscriptionRequest{Event: wps.Event_BlockClose, Scopes: []string{
		blockORef.String(),
	}}, nil)
	c.RpcClient.EventListener.On("blockclose", func(event *wps.WaveEvent) {
		c.doShutdown("got blockclose event")
	})
	return nil
}

func (c *Client) SendAsyncInitiation() error {
	if c.VDomContextBlockId == "" {
		return fmt.Errorf("no vdom context block id")
	}
	if c.GetIsDone() {
		return fmt.Errorf("client is done")
	}
	return wshclient.VDomAsyncInitiationCommand(

View on GitHub (pinned to a4447c1563)

Solutions

1. Confirm the block is actively rendered in the Wave window and reload the block if needed.
2. Restart the app so CreateVDomContext races less with frontend startup.
3. Increase WaitMs in CommandWaitForRouteData (e.g. to 10000) to tolerate slow frontend mounts.
4. Check the browser/renderer console in Wave for vdom context initialization errors.
5. Verify the vdom context type/name matches what the frontend component expects.

Example fix

// before
WaitMs: 4000,
// after
WaitMs: 10000, // tolerate slow frontend route registration

if blockORef.OID == "" {
    return fmt.Errorf("cannot wait for vdom route: empty block OID")
}

gotRoute, err := wshclient.WaitForRouteCommand(c.RpcClient, wshrpc.CommandWaitForRouteData{
    RouteId: wshutil.MakeFeBlockRouteId(blockORef.OID),
    WaitMs:  10000,
}, &wshrpc.RpcOpts{Timeout: 12000})
if err == nil && !gotRoute {
    // one retry after brief delay to absorb frontend startup races
    time.Sleep(500 * time.Millisecond)
    gotRoute, err = wshclient.WaitForRouteCommand(...)
}

When it happens

Trigger: Calling CreateVDomContext when the block's frontend component failed to mount, the block is minimized/backgrounded and vdom was never initialized, or the frontend route registration takes longer than 4000ms on a loaded machine.

Common situations: Very large vdom apps delaying frontend mount; Wave renderer crashed for that block; race where the app starts before the frontend finished loading the block.

Related errors

• error waiting for vdom context route: %v
• no webcontents found with blockid ${data.blockid}
• error getting wave file: + resp.statusText
• Layout model not found
• Block not found: ${blockId}

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