What causes "failed to init modules: %w" in gohugoio/hugo?

Pass an explicit module path: `hugo mod init github.com/me/mysite`.

failed to init modules: %w

Error message

failed to init modules: %w

What it means

Returned by Client.Init when `go mod init <path>` fails. Hugo runs this to turn the project into a Go Module (required for Hugo Modules); on success it records the go.mod path, so failure means the project cannot use module features.

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

Solutions

Pass an explicit module path: `hugo mod init github.com/me/mysite`.
If go.mod already exists, skip init — the project is already a module.
Ensure the `go` binary is installed and on PATH.
Use a valid module path (lowercase, domain-like prefix).

Example fix

# before
hugo mod init
# error: cannot determine module path
# after
hugo mod init github.com/me/mysite

Defensive patterns

Strategy: validation

Validate before calling

// only init when no go.mod exists yet
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
    // already initialized — skip Init
}

Try / catch

if err := client.Init(modPath); err != nil {
    return fmt.Errorf("module init failed (check go toolchain and write permissions in %s): %w", dir, err)
}

Prevention

Check for an existing go.mod before calling Init to avoid double-initialization
Verify the working directory is writable
Validate the module path passed to Init with module.CheckPath
Confirm the Go toolchain version meets Hugo's minimum requirement

When it happens

Trigger: Running `hugo mod init [path]` when `go mod init` exits non-zero: a go.mod already exists in the directory, an empty path Go cannot guess (not inside GOPATH/VCS), or an invalid module path.

Common situations: Re-running `hugo mod init` in an already-initialized project, running it with no path argument outside any VCS checkout so Go can't infer the module path, or Go binary missing/broken.

Related errors

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