{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/common/hexec/exec.go#L445-L481","documentation":"Produced by cmdWrapper.Run in common/hexec/exec.go:463 when an external binary Hugo invoked (PostCSS, asciidoctor, pandoc, dart-sass, etc.) exits with a non-zero status or otherwise fails, and the failure is not the 'binary not found' case (that gets a dedicated NotFoundError). The message includes the args passed and the process's captured stdout/stderr, so the real cause is usually in the trailing %s portion.","triggerScenarios":"Any hexec Runner.Run call where the child process fails: css.PostCSS/css.TailwindCSS pipelines, external content converters (asciidoctor, pandoc, rst2html), resources.ExecuteAsTemplate-adjacent tooling — whenever the tool exits non-zero or crashes with output not matching the not-found regex.","commonSituations":"Syntax errors in postcss.config.js or tailwind config, wrong tool version for the given flags, missing plugin dependencies inside the tool, the tool erroring on invalid input content, or OS-level failures (permissions, missing shared libraries).","solutions":["Read the embedded tool output at the end of the message — it is the child process's stderr and names the actual failure.","Run the same binary with the shown args manually from the project directory to reproduce and debug.","Fix the tool-side problem it reports (config syntax, missing plugin, version mismatch) and rebuild.","Check the binary's version matches what Hugo's pipeline expects and that its own dependencies are installed."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"# Confirm the external tool exists and runs before the Hugo build\ncommand -v asciidoctor >/dev/null && asciidoctor --version >/dev/null || exit 1","typeGuard":null,"tryCatchPattern":"if err := build(); err != nil && strings.Contains(err.Error(), \"failed to execute binary\") {\n    // the error string includes stderr — surface it verbatim and check the tool's own args/version\n}","preventionTips":["Test the external command (asciidoctor, pandoc, dart-sass, etc.) manually with the same args Hugo passes","Pin tool versions in CI images so argument changes across versions don't break builds","Whitelist required binaries in `security.exec.allow` and keep their dependencies installed"],"tags":["hugo","external-tools","subprocess","build-pipeline"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}