gohugoio/hugo · error

go command failed: %s

Error message

go command failed: %s

What it means

Emitted in `runGo` (modules/client.go:820) when the `go` command started successfully but exited non-zero (`*exec.ExitError`), and the failure wasn't one of the specially handled cases (go binary too old, unknown revision). Hugo surfaces go's captured stderr verbatim so the underlying toolchain problem (network, auth, go.mod issues) is visible to the user.

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 8a468df065)

Solutions

1. Read the embedded stderr text — it is go's own error and usually names the exact module and cause.
2. Verify the module path in your Hugo config exists and is reachable: `go list -m <path>@latest`.
3. For private modules set `GOPRIVATE=github.com/yourorg/*` and configure git credentials.
4. If checksum errors, run `hugo mod clean` then `hugo mod tidy` to refresh go.mod/go.sum.
5. Check GOPROXY/network access from the build environment.

Example fix

# before (hugo.toml)
[[module.imports]]
path = "github.com/user/my-privat-theme"  # typo, private, no auth
# after
# fix path and allow private access
[[module.imports]]
path = "github.com/user/my-private-theme"
# env: GOPRIVATE=github.com/user/*

// Pre-flight: run `go mod verify` / check network + GOPROXY before builds
// e.g. exec.Command("go", "env", "GOPROXY").Run()

if err := client.Get(mod); err != nil {
    var cerr *modules.ClientError // wraps stderr output
    if errors.As(err, &cerr) {
        log.Printf("go command stderr: %s", cerr.Err)
    }
    return err
}

When it happens

Trigger: `hugo mod get/tidy/vendor/graph/verify` or module collection during build, where `go` itself fails: unresolvable module path, network failure reaching proxy.golang.org, private repo auth failure, malformed go.mod, checksum mismatch against go.sum, or an invalid version query.

Common situations: Typo'd module path in `module.imports` in hugo config; private GitHub theme modules without GONOPRIVATE/credentials configured; offline or firewalled CI without GOPROXY access; stale go.sum after a module's tag was moved; GOFLAGS/GOPROXY misconfiguration.

Related errors

• module %q not found
• failed to execute 'go %v': %s %T
• invalid module path %q; must be relative to themesDir when d
• ErrNotExist
• %q not found

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