What causes "failed to execute binary %q with args %v: %s" in gohugoio/hugo?

Read the embedded tool output at the end of the message — it is the child process's stderr and names the actual failure.

gohugoio/hugo · error

failed to execute binary %q with args %v: %s

Error message

failed to execute binary %q with args %v: %s

What it means

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.

Source

Thrown at common/hexec/exec.go:463

type cmdWrapper struct {
	name string
	c    *exec.Cmd

	outerr *bytes.Buffer
}

var notFoundRe = regexp.MustCompile(`(?s)not found:|could not determine executable`)

func (c *cmdWrapper) Run() error {
	err := c.c.Run()
	if err == nil {
		return nil
	}
	if notFoundRe.MatchString(c.outerr.String()) {
		return &NotFoundError{name: c.name, method: "in PATH"}
	}
	return fmt.Errorf("failed to execute binary %q with args %v: %s", c.name, c.c.Args[1:], c.outerr.String())
}

func (c *cmdWrapper) StdinPipe() (io.WriteCloser, error) {
	return c.c.StdinPipe()
}

type commandeer struct {
	stdout io.Writer
	stderr io.Writer
	stdin  io.Reader
	dir    string
	ctx    context.Context

	name               string
	fullyQualifiedName string
	env                []string
}

View on GitHub ↗ (pinned to 8a468df065)

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.

Defensive patterns

Strategy: try-catch

Validate before calling

# Confirm the external tool exists and runs before the Hugo build
command -v asciidoctor >/dev/null && asciidoctor --version >/dev/null || exit 1

Try / catch

if err := build(); err != nil && strings.Contains(err.Error(), "failed to execute binary") {
    // the error string includes stderr — surface it verbatim and check the tool's own args/version
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/8830d2cdf716e8cc.json. Report an issue: GitHub ↗.