wavetermdev/waveterm · error

unknown connection status %q

Error message

unknown connection status %q

What it means

EnsureConnection()'s status switch has cases for init/disconnected/connecting/connected/error; this default-branch error means DeriveConnStatus returned a status string outside the known set — practically a state-machine invariant violation or a future/renamed status value.

Source

Thrown at pkg/wslconn/wslconn.go:776

	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)
	if conn == nil {
		return fmt.Errorf("client %q not found", connName)
	}
	err := conn.Close()
	return err
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Log the full unexpected status value from the error and check it against pkg/wslconn status constants
2. Update Wave/wsh to matching versions to avoid mixed-version status values
3. Reset the connection state via Disconnect and reconnect
4. If you modified status constants, add the missing case to EnsureConnection's switch
5. Report as a bug if seen on an unmodified install — this branch should be unreachable

Example fix

// developer fix
// before
case Status_Error:
    return fmt.Errorf("connection error: %s", connStatus.Error)
default:
    return fmt.Errorf("unknown connection status %q", connStatus.Status)
// after: add the new status to the switch
// case Status_New: return conn.Connect(ctx)

var validStatuses = map[string]bool{
    wslconn.Status_Init: true, wslconn.Status_Connecting: true,
    wslconn.Status_Connected: true, wslconn.Status_Disconnected: true,
    wslconn.Status_Error: true,
}
if !validStatuses[st.Status] {
    return fmt.Errorf("corrupt status %q; reset connection", st.Status)
}

func isKnownStatus(s string) bool {
    switch s {
    case wslconn.Status_Init, wslconn.Status_Connecting,
        wslconn.Status_Connected, wslconn.Status_Disconnected,
        wslconn.Status_Error:
        return true
    }
    return false
}

if err := wslconn.EnsureConnection(ctx, name); err != nil {
    if strings.HasPrefix(err.Error(), "unknown connection status") {
        // reset to a known state
        wslconn.DisconnectClient(name)
        return wslconn.EnsureConnection(ctx, name)
    }
    return err
}

When it happens

Trigger: DeriveConnStatus returns a status string not among init|connecting|connected|disconnected|error — only possible if a new status constant was added without updating EnsureConnection, or status was corrupted to an arbitrary string.

Common situations: Running a mixed-version setup where a newer backend reports a new status to an older command handler; custom code writing an invalid value into conn.Status; a bug in status derivation.

Related errors

• invalid term size: %v
• SwapToken is required in CommandOptsType
• unable to obtain client info: %w
• cannot connect to %q when status is %q
• error opening domain socket listener: %w

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