gohugoio/hugo · error

failed to execute 'go

Error message

failed to execute 'go %v': %s %T

What it means

In runGo, cmd.Run() returned an error that is neither *exec.Error (binary not found — handled separately) nor *exec.ExitError (normal non-zero exit — handled separately). That leaves failures in starting/running the process itself: the %T prints the concrete error type to aid diagnosis. Essentially 'something prevented the go process from running at all, and it wasn't a missing binary or a clean exit code.'

Solutions

1. Look at the %T and the wrapped error text: 'permission denied' → chmod/chown the go binary; 'resource temporarily unavailable' → raise ulimits.
2. Run the failing `go <args>` manually as the same user to reproduce.
3. In containers, raise `--ulimit nproc` and `--ulimit nofile` and confirm the go binary is executable and on PATH.
4. If context-cancellation, widen the timeout or avoid cancelling the build mid-flight.

Example fix

// before: container ulimits too low -> spawn fails
// after: raise limits
docker run --ulimit nofile=65536:65536 --ulimit nproc=4096:4096 ... hugo

// Validate the environment can spawn go before Hugo runs
func ensureGoRunnable() error {
  bin, err := exec.LookPath("go")
  if err != nil { return fmt.Errorf("go not on PATH: %w", err) }
  info, err := os.Stat(bin)
  if err != nil { return err }
  if info.Mode()&0o111 == 0 { return fmt.Errorf("go binary not executable: %s", bin) }
  // optional: probe spawn
  return exec.Command(bin, "env").Run()
}

null

null

When it happens

Trigger: exec.Cmd.Run fails before producing an ExitError — permission denied on the go binary, fork/limits exhaustion (EMFILE, EAGAIN), context cancellation surfacing as a non-Exit error, or an OS-level refusal to spawn the process.

Common situations: Container with low ulimits (nproc/nofile), read-only filesystem blocking the binary, SELinux/AppArmor denying exec, or Hugo invoked with a cancelled context (timeout).

Related errors

• failed to decode module download result
• failed to decode modules list
• failed to download module
• failed to download module
• failed to download modules

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/eba90a67ef3c9bc1. Report an issue: GitHub.

Appendix: source

Thrown at modules/client.go:811

			c.goBinaryStatus = goBinaryStatusNotFound
			return nil
		}

		if strings.Contains(stderr.String(), "invalid version: unknown revision") {
			// See https://github.com/gohugoio/hugo/issues/6825
			c.logger.Println(`An unknown revision most likely means that someone has deleted the remote ref (e.g. with a force push to GitHub).
To resolve this, you need to manually edit your go.mod file and replace the version for the module in question with a valid ref.

The easiest is to just enter a valid branch name there, e.g. master, which would be what you put in place of 'v0.5.1' in the example below.

require github.com/gohugoio/hugo-mod-jslibs/instantpage v0.5.1

If you then run 'hugo mod graph' it should resolve itself to the most recent version (or commit if no semver versions are available).`)
		}

		_, ok := err.(*exec.ExitError)
		if !ok {
			return fmt.Errorf("failed to execute 'go %v': %s %T", args, err, err)
		}

		// Too old Go version
		if strings.Contains(stderr.String(), "flag provided but not defined") {
			c.goBinaryStatus = goBinaryStatusTooOld
			return nil
		}

		return fmt.Errorf("go command failed: %s", stderr)

	}

	return nil
}

var goOutputReplacer = strings.NewReplacer(
	"go: to add module requirements and sums:", "hugo: to add module requirements and sums:",
	"go mod tidy", "hugo mod tidy",

View on GitHub (pinned to 52c9bd7908)