{"record":{"id":"b6fcfd1643eb9044","repo":"wavetermdev/waveterm","slug":"failed-to-start-process-w-b6fcfd","errorCode":null,"errorMessage":"failed to start process: %w","messagePattern":"failed to start process: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/genconn/genconn.go","lineNumber":82,"sourceCode":"}\n\nfunc RunSimpleCommand(ctx context.Context, client ShellClient, spec CommandSpec) (string, string, error) {\n\tproc, err := client.MakeProcessController(spec)\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"failed to create process controller: %w\", err)\n\t}\n\n\tstdout, err := proc.StdoutPipe()\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"failed to get stdout pipe: %w\", err)\n\t}\n\tstderr, err := proc.StderrPipe()\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"failed to get stderr pipe: %w\", err)\n\t}\n\n\tif err := proc.Start(); err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"failed to start process: %w\", err)\n\t}\n\n\tstdoutBuf := syncbuf.MakeSyncBuffer()\n\tstderrBuf := syncbuf.MakeSyncBuffer()\n\tvar wg sync.WaitGroup\n\twg.Add(2)\n\n\tgo func() {\n\t\tdefer wg.Done()\n\t\tio.Copy(stdoutBuf, stdout)\n\t}()\n\n\tgo func() {\n\t\tdefer wg.Done()\n\t\tio.Copy(stderrBuf, stderr)\n\t}()\n\n\trunErr := ProcessContextWait(ctx, proc)","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/genconn/genconn.go#L64-L100","documentation":"RunSimpleCommand calls proc.Start() to launch the prepared process; this error wraps any failure from starting it. The controller was created and both pipes were set up, so the failure is at exec/session-start time: the binary or shell was not found, working directory invalid, or the remote session rejected the exec request.","triggerScenarios":"proc.Start() errors: 'sh' not found on the remote (unlikely) or command path invalid; exec: chdir to a nonexistent Cwd; SSH 'request failed: channel' errors when the server refuses exec; resource limits (fork failure, EAGAIN) on the host.","commonSituations":"CommandSpec.Cwd pointing to a directory that does not exist on the remote; running commands on an overloaded remote that cannot fork; SSH server with exec disabled or restricted shells rejecting the request.","solutions":["Inspect the wrapped error: 'chdir ... no such file or directory' means fix CommandSpec.Cwd; 'fork/exec' resource errors mean check process/memory limits on the host.","Verify Cwd exists on the target machine before running (ls via a prior command).","For SSH 'request failed' errors, check sshd config (PermitUserShell / forced commands) and that the account has shell access.","Check that the remote has a POSIX shell (sh) available, since BuildShellCommand wraps everything in sh -c.","Retry after freeing resources if the cause is fork/EAGAIN under load."],"exampleFix":"// before\nspec := genconn.CommandSpec{Cmd: \"deploy.sh\", Cwd: \"/opt/app\"}\n_, _, err := genconn.RunSimpleCommand(ctx, client, spec)\n// after\ncwd := \"/opt/app\"\nif _, _, err := genconn.RunSimpleCommand(ctx, client, genconn.CommandSpec{Cmd: \"test -d \" + shellutil.HardQuote(cwd)}); err != nil {\n    return fmt.Errorf(\"remote cwd %s missing: %w\", cwd, err)\n}\nspec := genconn.CommandSpec{Cmd: \"deploy.sh\", Cwd: cwd}\n_, _, err := genconn.RunSimpleCommand(ctx, client, spec)","handlingStrategy":"validation","validationCode":"func validateSpec(ctx context.Context, client genconn.ShellClient, spec genconn.CommandSpec) error {\n    check := fmt.Sprintf(\"test -d %s && command -v sh\", shellutil.HardQuote(spec.Cwd))\n    _, stderr, err := genconn.RunSimpleCommand(ctx, client, genconn.CommandSpec{Cmd: check})\n    if err != nil {\n        return fmt.Errorf(\"remote env invalid (stderr: %s): %w\", stderr, err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"err := proc.Start() // or via RunSimpleCommand\nif err != nil {\n    var ee *exec.Error\n    if errors.As(err, &ee) {\n        return fmt.Errorf(\"binary %q not found on host\", ee.Name)\n    }\n    if strings.Contains(err.Error(), \"chdir\") {\n        return fmt.Errorf(\"cwd missing on host: %w\", err)\n    }\n    return fmt.Errorf(\"start failed: %w\", err)\n}","preventionTips":["Verify Cwd exists on the target before running","Confirm a POSIX shell exists on the remote (BuildShellCommand assumes sh -c)","Check sshd allows exec for the account","Watch for fork/resource limits on loaded hosts","Test commands against the specific platform (SSH vs WSL) before production use"],"tags":["process","exec","ssh","spawn"],"backgroundTag":"process-spawn-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}