{"record":{"id":"8830d2cdf716e8cc","repo":"gohugoio/hugo","slug":"failed-to-execute-binary-q-with-args-v-s","errorCode":null,"errorMessage":"failed to execute binary %q with args %v: %s","messagePattern":"failed to execute binary %q with args (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/hexec/exec.go","lineNumber":463,"sourceCode":"\ntype cmdWrapper struct {\n\tname string\n\tc    *exec.Cmd\n\n\touterr *bytes.Buffer\n}\n\nvar notFoundRe = regexp.MustCompile(`(?s)not found:|could not determine executable`)\n\nfunc (c *cmdWrapper) Run() error {\n\terr := c.c.Run()\n\tif err == nil {\n\t\treturn nil\n\t}\n\tif notFoundRe.MatchString(c.outerr.String()) {\n\t\treturn &NotFoundError{name: c.name, method: \"in PATH\"}\n\t}\n\treturn fmt.Errorf(\"failed to execute binary %q with args %v: %s\", c.name, c.c.Args[1:], c.outerr.String())\n}\n\nfunc (c *cmdWrapper) StdinPipe() (io.WriteCloser, error) {\n\treturn c.c.StdinPipe()\n}\n\ntype commandeer struct {\n\tstdout io.Writer\n\tstderr io.Writer\n\tstdin  io.Reader\n\tdir    string\n\tctx    context.Context\n\n\tname               string\n\tfullyQualifiedName string\n\tenv                []string\n}\n","sourceCodeStart":445,"sourceCodeEnd":481,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/common/hexec/exec.go#L445-L481","documentation":"Returned by cmdWrapper.Run when the underlying `os/exec` command fails for any reason other than a 'not found' message on stderr. The message embeds the binary name, the full args vector (excluding the binary itself), and the captured stderr buffer so the caller sees the tool's own error output.","triggerScenarios":"Calling Runner.Run() on a command built via Exec.New/Npx where the external process exits non-zero: a PostCSS config error, a missing asset referenced by the tool, a Node.js permission-model denial, a segfault, or invalid CLI flags.","commonSituations":"Asset processing pipelines (toCSS, PostCSS, Babel, Tailwind) failing because of a config error in the underlying tool, an unreachable import, or Node.js --permission denials when the security.allow list is too strict.","solutions":["Read the embedded stderr text in the message; it is the tool's own error.","Run the same binary with the same args manually in a shell to reproduce.","If the text mentions EPERM/permission-model, widen security.exec.allow or Node permissions config.","Check that all asset files referenced by the tool exist on disk."],"exampleFix":"// before\nif err := runner.Run(); err != nil { return err }\n// after\nif err := runner.Run(); err != nil {\n  var nf *hexec.NotFoundError\n  if errors.As(err, &nf) { /* missing binary path */ }\n  return fmt.Errorf(\"asset build failed: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := runner.Run(); err != nil {\n  var nf *hexec.NotFoundError\n  if errors.As(err, &nf) { /* install/PATH guidance */ }\n  // err already contains the tool's stderr; log and fail the asset build\n  return fmt.Errorf(\"build tool %q failed: %w\", name, err)\n}","preventionTips":["Surface the embedded stderr verbatim to users.","Distinguish NotFoundError from execution failure via errors.As.","Run the same command in a shell when debugging asset pipelines."],"tags":["hexec","run","external-process","stderr","pipeline"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}