gohugoio/hugo · error

go command failed

Error message

go command failed: %s

What it means

The catch-all in runGo for a normal non-zero go exit that did not match the special-cased strings (unknown revision, flag-not-defined/too-old). stderr is forwarded as the message. This is the most common go-side failure surfaced by Hugo module operations — any `go mod`/`go list` exit-code failure that isn't explicitly recognised.

Solutions

1. Read the forwarded stderr verbatim — it is the authoritative cause; act on it directly.
2. Common fix: `hugo mod tidy` to reconcile go.mod/go.sum.
3. If it names a missing replace target, fix the replace path in go.mod.
4. If it names a sum mismatch, `go clean -modcache` then `hugo mod tidy`.

Example fix

// stderr said: missing go.sum entry
// fix:
hugo mod tidy
hugo

// Pre-flight the most common go subcommands Hugo will invoke
func preflightGoModules(projectDir string) error {
  for _, args := range [][]string{{"mod", "download"}, {"list", "-m", "all"}} {
    cmd := exec.Command("go", args...)
    cmd.Dir = projectDir
    if out, err := cmd.CombinedOutput(); err != nil {
      return fmt.Errorf("go %s: %s", strings.Join(args, " "), out)
    }
  }
  return nil
}

null

// Treat any 'go command failed:' as authoritative stderr — show it to the user.
// if strings.HasPrefix(err.Error(), "go command failed:") { return errors.New(strings.TrimPrefix(err.Error(), "go command failed: ")) }

When it happens

Trigger: `go mod download`, `go list -m`, `go get`, etc. exit non-zero with stderr that isn't 'invalid version: unknown revision' or 'flag provided but not defined'. Includes sum verification failures, missing go entries, malformed go.mod, compile errors in a module's .go files, network errors during graph walk.

Common situations: go.sum out of date, go.mod has syntax errors, a dependency's .go file fails to build under the current toolchain, proxy auth expired, or a replaced local path missing.

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/8e1902be9f79315e. Report an issue: GitHub.

Appendix: source

Thrown at modules/client.go:820

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",
)

type goOutputReplacerWriter struct {
	w io.Writer
}

func (w goOutputReplacerWriter) Write(p []byte) (n int, err error) {
	s := goOutputReplacer.Replace(string(p))
	_, err = w.w.Write([]byte(s))

View on GitHub (pinned to 52c9bd7908)