What causes "WAVETERM_TABID environment variable not set" in wavetermdev/waveterm?

Run the `wsh ai` command from inside a Wave Terminal block, which sets WAVETERM_TABID automatically.

WAVETERM_TABID environment variable not set

Error message

WAVETERM_TABID environment variable not set

What it means

The `wsh ai` command needs to route RPC calls to the Wave terminal block that invoked it. It reads the WAVETERM_TABID environment variable, which Wave sets automatically when running wsh inside a terminal block. If the variable is empty, wsh cannot determine the target tab and returns this error instead of sending an RPC to an unknown route.

Source

Thrown at cmd/wsh/cmd/wshcmd-ai.go:165

			}
		}

		maxSize, sizeStr := getMaxFileSize(mimeType)
		if len(data) > maxSize {
			return fmt.Errorf("file %s exceeds maximum size of %s for %s files", fileName, sizeStr, mimeType)
		}

		allFiles = append(allFiles, wshrpc.AIAttachedFile{
			Name:   fileName,
			Type:   mimeType,
			Size:   len(data),
			Data64: base64.StdEncoding.EncodeToString(data),
		})
	}

	tabId := os.Getenv("WAVETERM_TABID")
	if tabId == "" {
		return fmt.Errorf("WAVETERM_TABID environment variable not set")
	}

	route := wshutil.MakeTabRouteId(tabId)

	if aiNewBlockFlag {
		newChatData := wshrpc.CommandWaveAIAddContextData{
			NewChat: true,
		}
		err := wshclient.WaveAIAddContextCommand(RpcClient, newChatData, &wshrpc.RpcOpts{
			Route:   route,
			Timeout: rpcTimeout,
		})
		if err != nil {
			return fmt.Errorf("creating new chat: %w", err)
		}
	}

	for _, file := range allFiles {

View on GitHub (pinned to a4447c1563)

Solutions

Run the `wsh ai` command from inside a Wave Terminal block, which sets WAVETERM_TABID automatically.
Verify the variable exists with `echo $WAVETERM_TABID`; if empty, reopen the command in a Wave block.
Avoid stripping the environment: don't use `sudo env -i`, `env -i`, or `docker exec` without `-e WAVETERM_TABID`.
If scripting, export WAVETERM_TABID=<tabid> manually to target a known tab.

Example fix

// before (plain terminal)
$ wsh ai --message "hello"  # error: WAVETERM_TABID not set

// after (inside Wave terminal block)
$ echo $WAVETERM_TABID  # non-empty
$ wsh ai --message "hello"

Defensive patterns

Strategy: validation

Validate before calling

if os.Getenv("WAVETERM_TABID") == "" {
    // run inside a Wave terminal block before invoking wsh ai
}

Try / catch

if err := runAI(); err != nil {
    if strings.Contains(err.Error(), "WAVETERM_TABID") {
        // fallback: prompt user to run inside Wave Terminal
    }
}

Prevention

Always execute wsh ai from inside a Wave terminal block.
Check `echo $WAVETERM_TABID` before scripting against wsh ai.
Avoid env-stripping wrappers (sudo env -i, docker exec without -e).

When it happens

Trigger: Running `wsh ai ...` (with aiRun in cmd/wsh/cmd/wshcmd-ai.go) outside a Wave terminal block, or in any shell where WAVETERM_TABID is unset — e.g. a plain system terminal, SSH session without wsh, CI runner, or a script that cleared the environment (env -i, sudo, docker exec).

Common situations: Developers testing `wsh ai` in a regular terminal or IDE shell instead of inside Wave; running the command via sudo/su which strips env vars; invoking from a cron job or CI pipeline where Wave's injected environment is absent.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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