wavetermdev/waveterm · error

creating new terminal block: %w

Error message

creating new terminal block: %w

What it means

wsh term creates a new terminal block in the Wave UI via the CreateBlockCommand RPC. When the RPC fails — typically because no Wave app is running to answer it, the connection/route is bad, or the server rejects the block-creation request — the CLI wraps the underlying error with this message.

Source

Thrown at cmd/wsh/cmd/wshcmd-term.go:82

	createMeta := map[string]any{
		waveobj.MetaKey_View:       "term",
		waveobj.MetaKey_CmdCwd:     cwd,
		waveobj.MetaKey_Controller: "shell",
	}
	if RpcContext.Conn != "" {
		createMeta[waveobj.MetaKey_Connection] = RpcContext.Conn
	}
	createBlockData := wshrpc.CommandCreateBlockData{
		TabId: tabId,
		BlockDef: &waveobj.BlockDef{
			Meta: createMeta,
		},
		Magnified: termMagnified,
		Focused:   true,
	}
	oref, err := wshclient.CreateBlockCommand(RpcClient, createBlockData, nil)
	if err != nil {
		return fmt.Errorf("creating new terminal block: %w", err)
	}
	WriteStdout("terminal block created: %s\n", oref)
	return nil
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Start the Wave Terminal app so an RPC server is available, then retry `wsh term`.
2. Check wsh connectivity/token setup (e.g. `wsh token` / wsheditordata) and re-run.
3. Inspect the wrapped %w error for the root cause (timeout vs. connection refused vs. server rejection).

Example fix

// before
oref, err := wshclient.CreateBlockCommand(RpcClient, createBlockData, nil)
if err != nil {
	return fmt.Errorf("creating new terminal block: %w", err)
}
// after
if RpcClient == nil {
	return fmt.Errorf("no wsh RPC connection: run this inside a Wave terminal")
}
oref, err := wshclient.CreateBlockCommand(RpcClient, createBlockData, nil)
if err != nil {
	return fmt.Errorf("creating new terminal block: %w", err)
}

// before calling wsh term, confirm a Wave app is reachable
if !isWaveAppRunning() {
	fmt.Fprintln(os.Stderr, "Wave Terminal is not running; start it before `wsh term`")
	os.Exit(1)
}

func hasRpcClient(c *wshrpc.RpcClient) bool { return c != nil }

oref, err := wshclient.CreateBlockCommand(RpcClient, createBlockData, nil)
if err != nil {
	if errors.Is(err, context.DeadlineExceeded) {
		// timeout: app hung or absent
	} else {
		// connection or rejection: check app running / token
	}
	return fmt.Errorf("creating new terminal block: %w", err)
}

When it happens

Trigger: Running `wsh term` (or `wsh term --magnified`) when CreateBlockCommand returns an error: no Wave app running, RPC connection failure, or server-side rejection of the create-block request.

Common situations: Invoking `wsh term` from a plain shell without a Wave terminal host available; a stale or mismatched wsh token; Wave app restarting while wsh connects.

Related errors

• playing system bell: %v
• watching pid: %v
• getting wsl connection status: %w
• reinstalling connection: %w
• disconnecting %q error: %w

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