What causes "failed to create WSL command" in wavetermdev/waveterm?

Verify the distro exists: run `wsl -l -v` (or wsl.exe --list) and confirm the distro name matches.

failed to create WSL command

Error message

failed to create WSL command

What it means

After building the command string, MakeWSLProcessController calls distro.WslCommand(context.Background(), fullCmd) to create an exec.Cmd that runs the command inside the WSL distro. If WslCommand returns nil, the constructor returns the plain error 'failed to create WSL command'. This indicates the distro wrapper could not produce a runnable command object.

Source

Thrown at pkg/genconn/wsl-impl.go:50

	lock        *sync.Mutex
	once        *sync.Once
	stdinPiped  bool
	stdoutPiped bool
	stderrPiped bool
	waitErr     error
	started     bool
	cmdSpec     CommandSpec
}

func MakeWSLProcessController(distro *wsl.Distro, cmdSpec CommandSpec) (*WSLProcessController, error) {
	fullCmd, err := BuildShellCommand(cmdSpec)
	if err != nil {
		return nil, fmt.Errorf("failed to build shell command: %w", err)
	}

	cmd := distro.WslCommand(context.Background(), fullCmd)
	if cmd == nil {
		return nil, fmt.Errorf("failed to create WSL command")
	}

	return &WSLProcessController{
		distro:  distro,
		cmd:     cmd,
		lock:    &sync.Mutex{},
		once:    &sync.Once{},
		cmdSpec: cmdSpec,
	}, nil
}

func (w *WSLProcessController) Start() error {
	w.lock.Lock()
	defer w.lock.Unlock()

	if w.started {
		return fmt.Errorf("command already started")
	}

View on GitHub (pinned to a4447c1563)

Solutions

Verify the distro exists: run `wsl -l -v` (or wsl.exe --list) and confirm the distro name matches.
Re-acquire the *wsl.Distro via the library's registered-distro lookup instead of a hand-constructed one.
Confirm WSL itself is functional (`wsl echo ok`) and wsl.exe is on PATH.
If WSL is broken, repair/reinstall the target distro.

Example fix

// before
distro := &wsl.Distro{Name: "ubuntu-22.04"} // may not exist
ctrl, err := genconn.MakeWSLProcessController(distro, spec) // nil WslCommand
// after
registered, err := wsl.GetRegisteredDistros(ctx)
if err != nil { return err }
if !slices.Contains(registered, "ubuntu-22.04") { return fmt.Errorf("distro missing") }
distro, _ := wsl.NewDistro(ctx, "ubuntu-22.04")
ctrl, err := genconn.MakeWSLProcessController(distro, spec)
if err != nil { return err }

Defensive patterns

Strategy: validation

Validate before calling

out, err := exec.Command("wsl.exe", "-l", "-q").Output()
if err != nil { return fmt.Errorf("WSL unavailable: %w", err) }
distros := strings.Fields(string(out))
if !slices.Contains(distros, distroName) {
    return fmt.Errorf("distro %q not registered; have %v", distroName, distros)
}

Try / catch

ctrl, err := genconn.MakeWSLProcessController(distro, spec)
if err != nil {
    if err.Error() == "failed to create WSL command" {
        return fmt.Errorf("distro invalid or WSL broken — run `wsl -l -v` to diagnose: %w", err)
    }
    return err
}

Prevention

Always resolve distros via the library's registered-distro listing, never hand-construct them.
Check WSL availability at app startup when WSL features are optional.
Pin/verify distro names in config against `wsl -l -q` output.
Handle `wsl --shutdown` / distro unregistration events if the app runs long-lived.

When it happens

Trigger: Calling MakeWSLProcessController with a distro whose WslCommand returns nil — typically a distro handle that is invalid/unregistered, or an internal failure mapping the command into the distro's environment.

Common situations: WSL distro specified by name no longer exists (wsl --unregister); WSL not installed or wsl.exe missing from PATH; distro object constructed with a bad name and never validated.

Related errors

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