{"record":{"id":"e517c20b3806bb01","repo":"wavetermdev/waveterm","slug":"failed-to-create-wsl-command","errorCode":null,"errorMessage":"failed to create WSL command","messagePattern":"failed to create WSL command","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/genconn/wsl-impl.go","lineNumber":50,"sourceCode":"\tlock        *sync.Mutex\n\tonce        *sync.Once\n\tstdinPiped  bool\n\tstdoutPiped bool\n\tstderrPiped bool\n\twaitErr     error\n\tstarted     bool\n\tcmdSpec     CommandSpec\n}\n\nfunc MakeWSLProcessController(distro *wsl.Distro, cmdSpec CommandSpec) (*WSLProcessController, error) {\n\tfullCmd, err := BuildShellCommand(cmdSpec)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to build shell command: %w\", err)\n\t}\n\n\tcmd := distro.WslCommand(context.Background(), fullCmd)\n\tif cmd == nil {\n\t\treturn nil, fmt.Errorf(\"failed to create WSL command\")\n\t}\n\n\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}","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/genconn/wsl-impl.go#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ndistro := &wsl.Distro{Name: \"ubuntu-22.04\"} // may not exist\nctrl, err := genconn.MakeWSLProcessController(distro, spec) // nil WslCommand\n// after\nregistered, err := wsl.GetRegisteredDistros(ctx)\nif err != nil { return err }\nif !slices.Contains(registered, \"ubuntu-22.04\") { return fmt.Errorf(\"distro missing\") }\ndistro, _ := wsl.NewDistro(ctx, \"ubuntu-22.04\")\nctrl, err := genconn.MakeWSLProcessController(distro, spec)\nif err != nil { return err }","handlingStrategy":"validation","validationCode":"out, err := exec.Command(\"wsl.exe\", \"-l\", \"-q\").Output()\nif err != nil { return fmt.Errorf(\"WSL unavailable: %w\", err) }\ndistros := strings.Fields(string(out))\nif !slices.Contains(distros, distroName) {\n    return fmt.Errorf(\"distro %q not registered; have %v\", distroName, distros)\n}","typeGuard":null,"tryCatchPattern":"ctrl, err := genconn.MakeWSLProcessController(distro, spec)\nif err != nil {\n    if err.Error() == \"failed to create WSL command\" {\n        return fmt.Errorf(\"distro invalid or WSL broken — run `wsl -l -v` to diagnose: %w\", err)\n    }\n    return err\n}","preventionTips":["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."],"tags":["wsl","windows","environment"],"backgroundTag":"wsl-distro-unavailable","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}