What causes "client %q not found" in wavetermdev/waveterm?

Treat the error as idempotent success if the goal is 'make sure it is disconnected' — ignore 'not found'

client %q not found

Error message

client %q not found

What it means

DisconnectClient() looks up the connection via getConnInternal and throws this when no connection with that name exists, before attempting conn.Close(). Note this uses the internal registry lookup, so it also fires for connections that were already closed and removed from the registry.

Source

Thrown at pkg/wslconn/wslconn.go:783

	connStatus := conn.DeriveConnStatus()
	switch connStatus.Status {
	case Status_Connected:
		return nil
	case Status_Connecting:
		return conn.WaitForConnect(ctx)
	case Status_Init, Status_Disconnected:
		return conn.Connect(ctx)
	case Status_Error:
		return fmt.Errorf("connection error: %s", connStatus.Error)
	default:
		return fmt.Errorf("unknown connection status %q", connStatus.Status)
	}
}

func DisconnectClient(connName string) error {
	conn := getConnInternal(connName)
	if conn == nil {
		return fmt.Errorf("client %q not found", connName)
	}
	err := conn.Close()
	return err
}

View on GitHub (pinned to a4447c1563)

Solutions

Treat the error as idempotent success if the goal is 'make sure it is disconnected' — ignore 'not found'
Check the connection exists first via DeriveConnStatus/GetConnections before disconnecting
Fix double-disconnect paths so cleanup runs exactly once
Verify the connName spelling against the registered connections

Example fix

// before
err := wslconn.DisconnectClient(connName) // 'client "x" not found' on second call
// after
if st := wslconn.DeriveConnStatusFor(connName); st != nil && st.Status != "" {
    err := wslconn.DisconnectClient(connName)
    if err != nil && strings.Contains(err.Error(), "not found") {
        err = nil // already disconnected
    }
}

Defensive patterns

Strategy: validation

Validate before calling

st := wslconn.DeriveConnStatusFor(connName)
if st == nil || st.Status == "" {
    return nil // already gone; nothing to disconnect
}
wslconn.DisconnectClient(connName)

Try / catch

err := wslconn.DisconnectClient(name)
if err != nil && strings.Contains(err.Error(), "not found") {
    err = nil // idempotent disconnect: already removed
}

Prevention

Make disconnect flows idempotent by ignoring 'not found'
Guard against double-click duplicate disconnect actions
Use a live connection list, not a stale snapshot, for cleanup loops
Track which connections your code owns and closed already

When it happens

Trigger: Calling DisconnectClient with an unknown or already-disconnected-and-forgotten connName — e.g. disconnecting twice, or disconnecting a name that was never connected.

Common situations: UI issued two disconnect actions in quick succession (double-click); a shutdown/cleanup routine iterates names from a stale snapshot while some were already closed; typo in the connection name.

Related errors

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