wavetermdev/waveterm · error

wsl distro %s not found

Error message

wsl distro %s not found

What it means

On Windows, GetDistroCmd enumerates registered WSL distributions via RegisteredDistros and matches by name. This error is returned when the requested wslDistroName does not match any installed distribution (or enumeration found nothing usable).

Source

Thrown at pkg/wsl/wsl-win.go:125

}

func (c *WslCmd) SetStderr(stderr io.Writer) {
	c.c.Stderr = stderr
}

func GetDistroCmd(ctx context.Context, wslDistroName string, cmd string) (*WslCmd, error) {
	distros, err := RegisteredDistros(ctx)
	if err != nil {
		return nil, err
	}
	for _, distro := range distros {
		if distro.Name() != wslDistroName {
			continue
		}
		wrappedDistro := Distro{distro}
		return wrappedDistro.WslCommand(ctx, cmd), nil
	}
	return nil, fmt.Errorf("wsl distro %s not found", wslDistroName)
}

func GetDistro(ctx context.Context, wslDistroName WslName) (*Distro, error) {
	distros, err := RegisteredDistros(ctx)
	if err != nil {
		return nil, err
	}
	for _, distro := range distros {
		if distro.Name() != wslDistroName.Distro {
			continue
		}
		wrappedDistro := Distro{distro}
		return &wrappedDistro, nil
	}
	return nil, fmt.Errorf("wsl distro %s not found", wslDistroName)
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Run 'wsl -l -v' (or wsl.RegisteredDistros) and use an exact name from the list in GetDistroCmd
2. Install the missing distro with 'wsl --install -d <DistroName>'
3. Update stale Wave connection configs to point at an installed distro
4. Ensure WSL is initialized (run 'wsl --status'); a broken WSL install can yield an empty distro list

Example fix

// before
cmd, err := wsl.GetDistroCmd(ctx, "Ubuntu-20.04", "ls")
// after
distros, _ := wsl.RegisteredDistros(ctx)
var name string
for _, d := range distros {
    if strings.HasPrefix(d.Name(), "Ubuntu") {
        name = d.Name()
        break
    }
}
cmd, err := wsl.GetDistroCmd(ctx, name, "ls")

func distroInstalled(ctx context.Context, name string) bool {
    distros, err := wsl.RegisteredDistros(ctx)
    if err != nil { return false }
    for _, d := range distros {
        if d.Name() == name { return true }
    }
    return false
}

cmd, err := wsl.GetDistroCmd(ctx, distroName, command)
if err != nil && strings.Contains(err.Error(), "not found") {
    return fmt.Errorf("distro %q is not installed; run 'wsl -l -v' and 'wsl --install -d %s'", distroName, distroName)
}

When it happens

Trigger: Calling wsl.GetDistroCmd on Windows with a distro name that is not installed (typo, distro uninstalled, name differing from wsl -l output), or when RegisteredDistros returns an empty list.

Common situations: Distro removed or upgraded (renamed) after a Wave connection was configured; referencing 'Ubuntu-20.04' when only 'Ubuntu-22.04' is installed; WSL never installed on the machine.

Related errors

• No tab view found for the given webContents id
• wsl connection not found: %s
• failed to create WSL command
• failed to start command: %w
• User redirected to docsite to learn more about ARM64 transla

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