wavetermdev/waveterm · error

wsl connection not found: %s

Error message

wsl connection not found: %s

What it means

When the block's target remote uses the wsl:// scheme, getConnUnion resolves the named WSL distribution via wslconn.GetWslConn. This error means no WSL connection/distribution with that name is registered — the distro name in meta:conn doesn't match any known WSL instance on this machine.

Source

Thrown at pkg/blockcontroller/shellcontroller.go:341

	ConnName   string
	ConnType   string
	SshConn    *conncontroller.SSHConn
	WslConn    *wslconn.WslConn
	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 {

View on GitHub (pinned to a4447c1563)

Solutions

1. Run `wsl -l -v` to list installed distributions and match the exact name (including case).
2. Reinstall/register the missing distro, or re-point the block's meta:conn at an existing one.
3. Ensure the WSL service is running and distros enumerate (wsl --status).
4. Trim typos/whitespace from the distro name in the block settings.

Example fix

// before
meta := waveobj.MetaMapType{"conn": "wsl://Ubuntu-20.04"} // uninstalled distro
// after
meta := waveobj.MetaMapType{"conn": "wsl://Ubuntu-22.04"} // name matching `wsl -l`

wslName := strings.TrimPrefix(remoteName, "wsl://")
if wslconn.GetWslConn(wslName) == nil {
    return fmt.Errorf("distro %q not found; run 'wsl -l -v' to list valid names", wslName)
}

if err := controller.Start(ctx, meta, rtOpts, false); err != nil {
    if strings.Contains(err.Error(), "wsl connection not found") {
        // refresh WSL distro list, prompt user to re-pick a distro
    }
    return err
}

When it happens

Trigger: remoteName has the wsl:// prefix and wslconn.GetWslConn(trimmedName) returns nil: distribution uninstalled, name mismatch (case/space), WSL not enumerating distros, or a stale meta:conn after the distro was removed.

Common situations: User removed a WSL distro (wsl --unregister) but a terminal block still references it; WSL service not running / freshly booted before distros enumerate; typo in distro name; WSL1 vs WSL2 naming differences.

Related errors

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

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