wavetermdev/waveterm · error

connection error: %s

Error message

connection error: %s

What it means

EnsureConnection() throws this when the connection's derived status is Status_Error, surfacing the stored connStatus.Error string. The connection previously failed (a prior connectInternal error set Status_Error), and instead of retrying, EnsureConnection reports the stored failure to the caller.

Source

Thrown at pkg/wslconn/wslconn.go:774

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

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the included connStatus.Error detail to find the root cause
2. Call Disconnect/Reconnect to reset state and retry the connect from Status_Disconnected
3. Verify the distro exists ('wsl -l -v') and starts cleanly; run 'wsl --shutdown' to clear stuck state
4. Check that wsl.exe is on PATH and WSL is properly installed
5. If the error persists, inspect connection logs (conn.Infof output) for the underlying failure

Example fix

// before
err := wslconn.EnsureConnection(ctx, name) // 'connection error: <stale error>'
// after
status := wslconn.DeriveConnStatusFor(name)
if status.Status == wslconn.Status_Error {
    wslconn.DisconnectClient(name) // reset state
}
err := wslconn.EnsureConnection(ctx, name)

st := wslconn.DeriveConnStatusFor(name)
if st != nil && st.Status == wslconn.Status_Error {
    // reset before ensure, otherwise EnsureConnection just re-reports the old error
    wslconn.DisconnectClient(name)
}

if err := wslconn.EnsureConnection(ctx, name); err != nil {
    if strings.HasPrefix(err.Error(), "connection error") {
        // reset and retry once
        wslconn.DisconnectClient(name)
        return wslconn.EnsureConnection(ctx, name)
    }
    return err
}

When it happens

Trigger: Calling EnsureConnection/ConnEnsureCommand for a connection whose last Connect() attempt failed and left Status='error' — e.g. distro unreachable, domain socket failure, or the double-connect error 1600 previously stored.

Common situations: WSL distro not running or uninstalled since last use; wsl.exe missing from PATH; previous connection attempt crashed leaving persistent error state; stale connection after Windows sleep/resume.

Related errors

• cannot connect to %q when status is %q
• window ${windowId} not found
• encryption is not available
• wsl connection %s not connected, cannot start shellproc
• invalid term size: %v

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