What causes "connection not found: %s" in wavetermdev/waveterm?

List available connections (connection: list / GetConnections) and use an exact registered name

connection not found: %s

Error message

connection not found: %s

What it means

EnsureConnection() looks up the connection by name via GetWslConn and throws this when no connection with that name is registered. It is the pre-flight check for RPC commands that require an established connection (e.g. ConnEnsureCommand).

Source

Thrown at pkg/wslconn/wslconn.go:763

		rtn = &WslConn{Lock: &sync.Mutex{}, Status: Status_Init, Name: connName, WshEnabled: &atomic.Bool{}, HasWaiter: &atomic.Bool{}, cancelFn: nil}
		clientControllerMap[name] = rtn
	}
	return rtn
}

func GetWslConn(name string) *WslConn {
	conn := getConnInternal(name)
	return conn
}

// Convenience function for ensuring a connection is established
func EnsureConnection(ctx context.Context, connName string) error {
	if connName == "" {
		return nil
	}
	conn := GetWslConn(connName)
	if conn == nil {
		return fmt.Errorf("connection not found: %s", connName)
	}
	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)

View on GitHub (pinned to a4447c1563)

Solutions

List available connections (connection: list / GetConnections) and use an exact registered name
Verify the connection profile still exists in the Wave config and re-add it if deleted
Check for typos/whitespace in connName and that you pass the connection name, not a host or alias
Reload config/restart Wave if the profile was just added and isn't yet registered

Example fix

// before
err := wslconn.EnsureConnection(ctx, "MyLaptop") // 'connection not found: MyLaptop'
// after
conns := wconfig.GetConnectionConfigs()
if _, ok := conns["MyLaptop"]; !ok {
    return fmt.Errorf("profile missing; create it first")
}
err := wslconn.EnsureConnection(ctx, "MyLaptop")

Defensive patterns

Strategy: validation

Validate before calling

func connectionExists(name string) bool {
    for _, c := range wslconn.GetConnections() {
        if c.GetName() == name {
            return true
        }
    }
    return false
}
if !connectionExists(connName) {
    return fmt.Errorf("profile %q does not exist", connName)
}

Type guard

func isKnownConn(c *wslconn.WslConn) bool { return c != nil }

Try / catch

if err := wslconn.EnsureConnection(ctx, name); err != nil {
    if strings.HasPrefix(err.Error(), "connection not found") {
        return fmt.Errorf("profile %q missing; pick from connection: list", name)
    }
    return err
}

Prevention

Validate connection names against the config before use
Update references after renaming/deleting profiles
Use connection pickers rather than free-text input
Reload config after manual edits

When it happens

Trigger: Calling EnsureConnection/ConnEnsureCommand with a connName that has no registered WSLConn — typo in the connection name, the profile was deleted, or the connection was never initialized because its config isn't loaded.

Common situations: Renamed or deleted a connection profile in Wave but a block/command still references the old name; passing a host identifier instead of the connection name; config file edited by hand with a stale connection name.

Related errors

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