wavetermdev/waveterm · error

setting background: %v

Error message

setting background: %v

What it means

After building the metadata, setbg sends it to the running Wave Terminal via the SetMetaCommand wsh RPC with a 2-second timeout. Any RPC failure — no connected terminal, connection dropped, remote not reachable, timeout, or server-side rejection — is wrapped as "setting background". The local validation succeeded but the change was not applied.

Source

Thrown at cmd/wsh/cmd/wshcmd-setbg.go:225

	// Resolve tab reference
	id := blockArg
	if id == "" {
		id = "tab"
	}
	oRef, err := resolveSimpleId(id)
	if err != nil {
		return err
	}

	// Send RPC request
	setMetaWshCmd := wshrpc.CommandSetMetaData{
		ORef: *oRef,
		Meta: meta,
	}
	err = wshclient.SetMetaCommand(RpcClient, setMetaWshCmd, &wshrpc.RpcOpts{Timeout: 2000})
	if err != nil {
		return fmt.Errorf("setting background: %v", err)
	}

	WriteStdout("background set\n")
	return nil
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Run the command from inside a Wave Terminal block (wsh requires an active connection)
2. Retry the command — transient network/timeout issues often resolve on a second attempt
3. Verify the block ID passed with --block still exists in the current window
4. Check the Wave Terminal connection is alive (try another wsh command like `wsh ls`)

# confirm you are inside a waveterm-connected context first
wsh ls / >/dev/null 2>&1 || { echo "wsh has no terminal connection" >&2; exit 1; }

const { execSync } = require("child_process");
for (let attempt = 1; attempt <= 3; attempt++) {
  try { execSync(`wsh setbg "${img}"`); break; }
  catch (e) {
    if (String(e.stderr).includes("setting background") && attempt < 3) continue;
    throw e;
  }
}

When it happens

Trigger: Running `wsh setbg` outside a Wave Terminal context (no block/tab connection), the terminal connection dropped mid-command, the target tab/block (resolved via --block or the default "tab") is gone, or the RPC exceeded the 2000ms timeout because the terminal is hung or on a slow remote (SSH) connection.

Common situations: Running wsh from a plain system shell not attached to Wave; stale block ID passed with --block after closing that block; slow SSH remotes timing out; waveterm backend restarting during the call.

Related errors

• setting config: %w
• running view command: %w
• playing system bell: %v
• watching pid: %v
• failed to list workspaces: %v

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