wavetermdev/waveterm · error

wsl connection %s not connected, cannot start shellproc

Error message

wsl connection %s not connected, cannot start shellproc

What it means

Thrown by getConnUnion when the named WSL connection exists (GetWslConn returned it) but its DerivedConnStatus is not Status_Connected. Wave refuses to start a shell process in a WSL distro whose connection is not fully established, since commands could not be reliably executed there.

Source

Thrown at pkg/blockcontroller/shellcontroller.go:345

	WshEnabled bool
	ShellPath  string
	ShellOpts  []string
	ShellType  string
	HomeDir    string
}

func (bc *ShellController) getConnUnion(logCtx context.Context, remoteName string, blockMeta waveobj.MetaMapType) (ConnUnion, error) {
	rtn := ConnUnion{ConnName: remoteName}
	wshEnabled := !blockMeta.GetBool(waveobj.MetaKey_CmdNoWsh, false)
	if strings.HasPrefix(remoteName, "wsl://") {
		wslName := strings.TrimPrefix(remoteName, "wsl://")
		wslConn := wslconn.GetWslConn(wslName)
		if wslConn == nil {
			return ConnUnion{}, fmt.Errorf("wsl connection not found: %s", remoteName)
		}
		connStatus := wslConn.DeriveConnStatus()
		if connStatus.Status != conncontroller.Status_Connected {
			return ConnUnion{}, fmt.Errorf("wsl connection %s not connected, cannot start shellproc", remoteName)
		}
		rtn.ConnType = ConnType_Wsl
		rtn.WslConn = wslConn
		rtn.WshEnabled = wshEnabled && wslConn.WshEnabled.Load()
	} else if conncontroller.IsLocalConnName(remoteName) {
		rtn.ConnType = ConnType_Local
		rtn.WshEnabled = wshEnabled
	} else {
		opts, err := remote.ParseOpts(remoteName)
		if err != nil {
			return ConnUnion{}, fmt.Errorf("invalid ssh remote name (%s): %w", remoteName, err)
		}
		conn := conncontroller.MaybeGetConn(opts)
		if conn == nil {
			return ConnUnion{}, fmt.Errorf("ssh connection not found: %s", remoteName)
		}
		connStatus := conn.DeriveConnStatus()
		if connStatus.Status != conncontroller.Status_Connected {

View on GitHub (pinned to a4447c1563)

Solutions

1. Wait for the WSL connection to reach Status_Connected (watch DeriveConnStatus) and retry the shell command
2. Reconnect the WSL connection explicitly (trigger the connection controller's connect flow) before starting the shell
3. Check that the WSL distro itself is healthy: `wsl -l -v` shows Running and `wsl -d <distro> echo ok` works
4. Restart Wave Terminal so the WSL connection is re-established from scratch

Example fix

// before: immediately starting shell after resolving conn
shellProc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)

// after: verify connection status first
connStatus := wslconn.GetWslConn(wslName).DeriveConnStatus()
if connStatus.Status != conncontroller.Status_Connected {
    // reconnect or surface 'connecting...' UI before retry
    return fmt.Errorf("wsl %s still connecting, retry later", wslName)
}
shellProc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)

wslConn := wslconn.GetWslConn(wslName)
if wslConn == nil || wslConn.DeriveConnStatus().Status != conncontroller.Status_Connected {
    return fmt.Errorf("wsl %s not ready; wait for connected state", wslName)
}

func isWslConnected(c *wslconn.WslConn) bool {
    return c != nil && c.DeriveConnStatus().Status == conncontroller.Status_Connected
}

proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)
if err != nil && strings.Contains(err.Error(), "not connected, cannot start shellproc") {
    // schedule retry after connection-state event signals Connected
}

When it happens

Trigger: Calling DoRunShellCommand / setupAndStartShellProcess for a block whose remoteName maps to a WSL distro while wslconn.GetWslConn(wslName) returns a connection whose DeriveConnStatus().Status is Connecting, Error, or Disconnected.

Common situations: WSL distro still booting or the wsh connection handshake still in progress; the distro was registered but the underlying wsl.exe process exited; network/auth issues interrupted the WSL bridge; user reopened a terminal block right after app start before the connection reconnected.

Related errors

• window ${windowId} not found
• encryption is not available
• cannot connect to %q when status is %q
• connection error: %s
• No tab view found for the given webContents id

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