What causes "client id cannot be empty" in wavetermdev/waveterm?

Generate/assign a valid client id before calling client methods (uuid, hostname+pid, etc.)

client id cannot be empty

Error message

client id cannot be empty

What it means

Validation error from the tsunami client: creating or resolving a client requires a non-empty client ID. An empty ID cannot identify the client to the engine, so the call is rejected immediately.

Source

Thrown at tsunami/engine/clientimpl.go:129

		RootElem:        vdom.H(DefaultComponentName, nil),
	}
	client.Root = MakeRoot(client)
	return client
}

func GetDefaultClient() *ClientImpl {
	return defaultClient
}

func (c *ClientImpl) GetIsDone() bool {
	c.Lock.Lock()
	defer c.Lock.Unlock()
	return c.IsDone
}

func (c *ClientImpl) checkClientId(clientId string) error {
	if clientId == "" {
		return fmt.Errorf("client id cannot be empty")
	}
	c.Lock.Lock()
	defer c.Lock.Unlock()
	if c.CurrentClientId == "" || c.CurrentClientId == clientId {
		c.CurrentClientId = clientId
		return nil
	}
	return fmt.Errorf("client id mismatch: expected %s, got %s", c.CurrentClientId, clientId)
}

func (c *ClientImpl) clientTakeover(clientId string) {
	c.Lock.Lock()
	defer c.Lock.Unlock()
	c.CurrentClientId = clientId
}

func (c *ClientImpl) doShutdown(reason string) {
	c.Lock.Lock()

View on GitHub (pinned to a4447c1563)

Solutions

Generate/assign a valid client id before calling client methods (uuid, hostname+pid, etc.)
Validate the id non-empty at config load time
Check where the id originates (server handshake response) and handle empty values there

Example fix

// before
client.Send(cfg.ClientID, msg) // cfg.ClientID == ""
// after
if cfg.ClientID == "" {
    return errors.New("client id must be configured")
}
client.Send(cfg.ClientID, msg)

Defensive patterns

Strategy: validation

Validate before calling

if clientID == "" {
    return errors.New("client id must be non-empty before calling client")
}
client.Send(clientID, msg)

Type guard

func validClientID(id string) bool { return strings.TrimSpace(id) != "" }

Try / catch

if err := client.Send(id, msg); err != nil {
    if strings.Contains(err.Error(), "client id cannot be empty") {
        id = generateNewID() // recover by minting a fresh id
    }
}

Prevention

Validate the id at config load time
Mint ids with uuid.NewString() before first client call
Never propagate a server-returned id without checking non-empty

When it happens

Trigger: Calling any ClientImpl method that delegates to checkClientId with clientId == "" — e.g. after a failed registration that never produced an id, or constructing the id from an unset config value.

Common situations: Config file missing the client id field; empty environment variable interpolated into the id; server returned an empty id on first connect and the client code propagated it.

Related errors

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