wavetermdev/waveterm · error

disconnected

Error message

disconnected

What it means

WaitForConnect returns this error when DeriveConnStatus reports Status_Init or Status_Disconnected instead of Connected or Connecting — i.e. the connection is not being attempted at all or was torn down. The connect will never succeed in this state, so waiting is aborted immediately.

Solutions

1. Start the connection first: call conn.Connect(ctx) (or Reconnect) before WaitForConnect
2. Check the connection status (DeriveConnStatus) and any stored WshError/NoWshReason for the disconnect reason
3. Verify WSL is installed and the distro exists: 'wsl -l -v'
4. If the distro shut down, reconnect — WSL terminates idle distros automatically

Example fix

// before: wait without connecting
err := conn.WaitForConnect(ctx)
// after
if s := conn.DeriveConnStatus().Status; s == Status_Init || s == Status_Disconnected {
    if err := conn.Connect(ctx); err != nil {
        return err
    }
}
err := conn.WaitForConnect(ctx)

st := conn.DeriveConnStatus().Status
if st == Status_Init || st == Status_Disconnected {
    if err := conn.Connect(ctx); err != nil {
        return err
    }
}
err := conn.WaitForConnect(ctx)

func waitingMakesSense(conn *wslconn.WslConn) bool {
    st := conn.DeriveConnStatus().Status
    return st == wslconn.Status_Connecting || st == wslconn.Status_Init
}

if err := conn.WaitForConnect(ctx); err != nil {
    if err.Error() == "disconnected" {
        // (re)start the connection, then wait again
        if cerr := conn.Connect(ctx); cerr != nil {
            return cerr
        }
        err = conn.WaitForConnect(ctx)
    }
}

When it happens

Trigger: Calling WaitForConnect before Connect() was ever started (Status_Init), or after the connection dropped/was closed (Status_Disconnected); the WSL distro failed to launch so the state reverted to disconnected.

Common situations: Calling WaitForConnect on a connection whose Connect failed earlier; wsl.exe unavailable or WSL not installed; the distro was unregistered or shut down between connect attempts; a race where Connect finished/failed before WaitForConnect began.

Related errors

• context timeout
• error
• failed to create process controller
• GetDistro not implemented on this system
• not connected

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

Appendix: source

Thrown at pkg/wslconn/wslconn.go:481

	return conn.Connect(ctx)
}

func (conn *WslConn) WaitForConnect(ctx context.Context) error {
	for {
		status := conn.DeriveConnStatus()
		if status.Status == Status_Connected {
			return nil
		}
		if status.Status == Status_Connecting {
			select {
			case <-ctx.Done():
				return fmt.Errorf("context timeout")
			case <-time.After(100 * time.Millisecond):
				continue
			}
		}
		if status.Status == Status_Init || status.Status == Status_Disconnected {
			return fmt.Errorf("disconnected")
		}
		if status.Status == Status_Error {
			return fmt.Errorf("error: %v", status.Error)
		}
		return fmt.Errorf("unknown status: %q", status.Status)
	}
}

// does not return an error since that error is stored inside of WslConn
func (conn *WslConn) Connect(ctx context.Context) error {
	var connectAllowed bool
	conn.WithLock(func() {
		if conn.Status == Status_Connecting || conn.Status == Status_Connected {
			connectAllowed = false
		} else {
			conn.Status = Status_Connecting
			conn.Error = ""
			connectAllowed = true

View on GitHub (pinned to a4447c1563)