gohugoio/hugo · error

failed to init modules

Error message

failed to init modules: %w

What it means

Returned by Client.Init when c.runGo(... "mod" "init" <path>) fails, i.e. `go mod init <path>` exited non-zero. Wrapped with %w. On success the client sets GoModulesFilename so the project is treated as a Go module. The error usually means Go is not installed (though runGo records not-found silently, a real failure here is typically an invalid module path or an existing go.mod).

Solutions

1. Provide a valid Go module path: a domain-prefixed path like 'github.com/user/project'.
2. Remove or back up an existing go.mod before running `hugo mod init` if you intend a fresh init.
3. Ensure the go toolchain is installed and recent: `go version`.
4. Reproduce with `go mod init <path>` directly to see Go's own error.

Example fix

# before
hugo mod init mysite   # invalid: not a valid module path

# after
hugo mod init github.com/user/mysite

// Validate the module path before running hugo mod init.
func validModulePath(path string) error {
    return module.CheckPath(path)
}

func isValidModulePath(path string) bool {
    return module.CheckPath(path) == nil
}

if err := client.Init(path); err != nil {
    // likely invalid path or existing go.mod; surface go's message and retry
}

When it happens

Trigger: Running `hugo mod init <path>` with a module path that violates Go module path rules (module.CheckPath), or when a go.mod already exists and Go refuses to re-init, or when Go is too old/absent in a way runGo does not silently swallow.

Common situations: Using a module path without a domain prefix (e.g. 'mysite' instead of 'github.com/user/mysite'); a go.mod already present in WorkingDir; corporate machine with a Go version older than Hugo requires; CI image missing the go toolchain.

Related errors

• failed to get
• failed to init config
• failed to load modules
• invalid module config for
• alias "" is an empty string

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

Appendix: source

Thrown at modules/client.go:369

	}

	return c.get(args...)
}

func (c *Client) get(args ...string) error {
	if err := c.runGo(context.Background(), c.logger.StdOut(), append([]string{"get"}, args...)...); err != nil {
		return fmt.Errorf("failed to get %q: %w", args, err)
	}
	return nil
}

// Init initializes this as a Go Module with the given path.
// If path is empty, Go will try to guess.
// If this succeeds, this project will be marked as Go Module.
func (c *Client) Init(path string) error {
	err := c.runGo(context.Background(), c.logger.StdOut(), "mod", "init", path)
	if err != nil {
		return fmt.Errorf("failed to init modules: %w", err)
	}

	c.GoModulesFilename = filepath.Join(c.ccfg.WorkingDir, goModFilename)

	return nil
}

var verifyErrorDirRe = regexp.MustCompile(`dir has been modified \((.*?)\)`)

// Verify checks that the dependencies of the current module,
// which are stored in a local downloaded source cache, have not been
// modified since being downloaded.
func (c *Client) Verify(clean bool) error {
	// TODO(bep) add path to mod clean
	err := c.runVerify()
	if err != nil {
		if clean {
			m := verifyErrorDirRe.FindAllStringSubmatch(err.Error(), -1)

View on GitHub (pinned to 52c9bd7908)