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.

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)

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

• not connected: %s
• wsl connection not found: %s
• failed to create process controller: %w
• GetDistro not implemented on this system
• context timeout

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