{"record":{"id":"2eb2f720471d6411","repo":"wavetermdev/waveterm","slug":"failed-to-start-command-w-2eb2f7","errorCode":null,"errorMessage":"failed to start command: %w","messagePattern":"failed to start command: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/genconn/wsl-impl.go","lineNumber":71,"sourceCode":"\treturn &WSLProcessController{\n\t\tdistro:  distro,\n\t\tcmd:     cmd,\n\t\tlock:    &sync.Mutex{},\n\t\tonce:    &sync.Once{},\n\t\tcmdSpec: cmdSpec,\n\t}, nil\n}\n\nfunc (w *WSLProcessController) Start() error {\n\tw.lock.Lock()\n\tdefer w.lock.Unlock()\n\n\tif w.started {\n\t\treturn fmt.Errorf(\"command already started\")\n\t}\n\n\tif err := w.cmd.Start(); err != nil {\n\t\treturn fmt.Errorf(\"failed to start command: %w\", err)\n\t}\n\n\tw.started = true\n\treturn nil\n}\n\nfunc (w *WSLProcessController) Wait() error {\n\tw.once.Do(func() {\n\t\tw.waitErr = w.cmd.Wait()\n\t})\n\treturn w.waitErr\n}\n\nfunc (w *WSLProcessController) Kill() {\n\tw.lock.Lock()\n\tdefer w.lock.Unlock()\n\n\tif w.cmd == nil {","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/genconn/wsl-impl.go#L53-L89","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nctrl, _ := genconn.MakeWSLProcessController(distro, spec)\nerr := ctrl.Start() // fails: exec: \"wsl.exe\": executable file not found in %PATH%\n// after\nif _, err := exec.LookPath(\"wsl.exe\"); err != nil {\n    return fmt.Errorf(\"wsl.exe not on PATH: %w\", err)\n}\nif err := ctrl.Start(); err != nil { return err }","handlingStrategy":"try-catch","validationCode":"if _, err := exec.LookPath(\"wsl.exe\"); err != nil {\n    return fmt.Errorf(\"wsl.exe not found on PATH: %w\", err)\n}\nif err := exec.Command(\"wsl.exe\", \"-l\", \"-q\").Run(); err != nil {\n    return fmt.Errorf(\"WSL service not responding: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := ctrl.Start(); err != nil {\n    if errors.Is(err, exec.ErrNotFound) {\n        return fmt.Errorf(\"wsl.exe missing from PATH: %w\", err)\n    }\n    return fmt.Errorf(\"could not launch WSL process: %w\", err)\n}","preventionTips":["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."],"tags":["wsl","windows","process-start"],"backgroundTag":"process-start-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}