In Go's os/exec, how do you tell a child's nonzero exit from a failure to launch it at all?

## Three outcomes, one error value When you run an external program there are three things that can happen, and `os/exec` encodes all of them in the single `error` returned by `Run`, `Output` or `CombinedOutput`: 1. **It ran and succeeded.** The error is `nil`. That is the *only* meaning of nil here — it is a statement about the exit status, not merely about the launch. 2. **It ran and failed.** The error is an `*exec.ExitError`. 3. **It never ran.** The error is something else entirely. Collapsing 2 and 3 into "the command failed" is the mistake that produces the worst incidents, because the operational response differs completely: a nonzero exit is the tool telling you something about your input, while a launch failure means the host is not set up the way you assumed. ## Distinguishing them ```go out, err := exec.Command(bin, "apply", "-f", "service.yaml").CombinedOutput() var ee *exec.ExitError switch { case err == nil: return nil case errors.As(err, &ee): return fmt.Errorf("apply exited %d: %s", ee.ExitCode(), out) default: return fmt.Errorf("apply could not start: %w", err) } ``` `errors.As` rather than a type assertion, because your own wrapping (or the package's) may sit in between. ### `*exec.ExitError` It embeds `*os.ProcessState`, so the state's methods are promoted onto it: - `ExitCode()` — the status the program exited with. It returns `-1` when the process has not exited normally, most commonly because it was terminated by a signal. Treat `-1` as "it did not choose to exit", not as "code minus one". - The state also tells you whether it exited at all, and carries the platform-specific status for the cases where you need the signal. - The `Stderr` field holds captured standard error **only** if the error came from `Output` with a nil `Cmd.Stderr`. After `Run` or `CombinedOutput` it is empty, and reaching for it there is a common source of blank error messages. ### Launch failures - **Program not found.** `exec.Command` calls `exec.LookPath` up front and stores the failure in `Cmd.Err`; running the command returns an `*exec.Error` (which has the attempted `Name` and the underlying `Err`) satisfying `errors.Is(err, exec.ErrNotFound)`. - **Found but not executable, wrong architecture, missing loader.** These surface as operating-system errors from the attempt to start the process, typically a path error naming the file. - **Bad `Cmd.Dir`.** A working directory that does not exist fails at start, not at exit. None of these is an `*exec.ExitError`, and none of them produces a meaningful exit code — which is why code that reaches straight for `ExitCode()` after a type assertion will panic or mislead. ## The failure this question exists for A deployment orchestrator replaces a shell script. The shell script had `set -e`, so any nonzero exit stopped it. The Go rewrite has, at one of forty call sites: ```go out, _ := exec.Command(bin, "apply", "-f", f).Output() log.Printf("applied %s: %s", f, out) ``` The underscore is the bug. The tool exits 1, `out` is empty, the log line prints happily with nothing after the colon, and the pipeline goes green on a deploy that did not happen. Nothing in the language warns you: discarding an error is legal, and the empty output looks like a quiet success. Three things make this class of defect visible: - **Never discard the error from a subprocess.** A vet-style check for ignored errors, or simply a review rule, catches it. Ignoring the *output* is fine; ignoring the *error* never is. - **Put the child's own words in yours.** `%s` on the captured bytes plus the exit code turns `exit status 1` into a message someone on call can act on without reproducing the run. - **Distinguish the two failure classes in the message.** "exited 2" and "could not start" route to different people. ## Exit codes as a contract If you branch on specific codes — treating 2 as "nothing to do" and anything else as fatal, say — you have taken a dependency on the tool's documented exit-code table. That is a legitimate thing to do and often much better than matching on message text, but write down which codes you rely on, because a tool upgrade can add or reassign them. Codes above 128 conventionally indicate a signal in shell reporting, but that is the *shell's* convention: in Go a signalled child gives you `-1` from `ExitCode()` and the signal itself from the process state.