What causes "failed to start command: %w" in wavetermdev/waveterm?

Check the wrapped error: exec.ErrNotFound / 'executable file not found' means fix PATH so wsl.exe is reachable.

failed to start command: %w

Error message

failed to start command: %w

What it means

WSLProcessController.Start calls cmd.Start() on the exec.Cmd created by distro.WslCommand. If the underlying OS process cannot be launched (exec.Cmd.Start error), it is wrapped as 'failed to start command'. The WSL command exists but Windows could not launch wsl.exe or the process inside the distro failed to spawn.

Source

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

	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")
	}

	if err := w.cmd.Start(); err != nil {
		return fmt.Errorf("failed to start command: %w", err)
	}

	w.started = true
	return nil
}

func (w *WSLProcessController) Wait() error {
	w.once.Do(func() {
		w.waitErr = w.cmd.Wait()
	})
	return w.waitErr
}

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

	if w.cmd == nil {

View on GitHub (pinned to a4447c1563)

Solutions

Check the wrapped error: exec.ErrNotFound / 'executable file not found' means fix PATH so wsl.exe is reachable.
Verify WSL health: run `wsl -l -v` and `wsl echo ok` manually in the same environment.
Start/restart the WSL service (wsl --shutdown, then retry; check LxssManager/WslService).
Repair or re-register the distro if its init consistently fails.

Example fix

// before
ctrl, _ := genconn.MakeWSLProcessController(distro, spec)
err := ctrl.Start() // fails: exec: "wsl.exe": executable file not found in %PATH%
// after
if _, err := exec.LookPath("wsl.exe"); err != nil {
    return fmt.Errorf("wsl.exe not on PATH: %w", err)
}
if err := ctrl.Start(); err != nil { return err }

Defensive patterns

Strategy: try-catch

Validate before calling

if _, err := exec.LookPath("wsl.exe"); err != nil {
    return fmt.Errorf("wsl.exe not found on PATH: %w", err)
}
if err := exec.Command("wsl.exe", "-l", "-q").Run(); err != nil {
    return fmt.Errorf("WSL service not responding: %w", err)
}

Try / catch

if err := ctrl.Start(); err != nil {
    if errors.Is(err, exec.ErrNotFound) {
        return fmt.Errorf("wsl.exe missing from PATH: %w", err)
    }
    return fmt.Errorf("could not launch WSL process: %w", err)
}

Prevention

Ensure wsl.exe is on PATH for every execution context (services use a minimal PATH).
Probe WSL health (wsl echo ok) before spawning workload commands.
Call Start only once per controller; check the started state to avoid double-start confusion.
On failure, run `wsl --shutdown` once and retry before giving up.

When it happens

Trigger: Calling Start() when wsl.exe cannot be executed (not on PATH, missing), the distro is stopped and fails to boot, or the process inside the distro cannot be created (resource limits, distro terminated mid-start).

Common situations: wsl.exe absent from PATH in the current environment (services, non-interactive contexts); WSL service (LxssManager / WslService) not running; distro corrupted so its init fails; Windows permissions blocking process creation.

Related errors

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