What causes ": %w" in gohugoio/hugo?

Run 'hugo mod tidy' to download and reconcile module dependencies.

: %w

Error message

: %w

What it means

Produced by collector.wrapModuleNotFound (modules/collect.go:888). When a referenced Go module cannot be resolved/downloaded, the original error is reformatted and wrapped with modules.ErrNotExist so callers can detect 'not found' via errors.Is. The empty-message leading ": %w" means the wrapped error carries its own message; this is a re-wrapping point, not a user-authored message.

Source

Thrown at modules/collect.go:888

		if !files.IsComponentFolder(targetBase) {
			return nil, fmt.Errorf("%s: mount target must be one of: %v", errMsg, files.ComponentFolders)
		}

		if err := mnt.init(c.logger.Logger()); err != nil {
			return nil, fmt.Errorf("%s: %w", errMsg, err)
		}

		out = append(out, mnt)
	}

	return out, nil
}

func (c *collector) wrapModuleNotFound(err error) error {
	if c.Client.ccfg.IgnoreModuleDoesNotExist {
		return nil
	}
	err = fmt.Errorf(err.Error()+": %w", ErrNotExist)
	if c.GoModulesFilename == "" {
		return err
	}

	baseMsg := "we found a go.mod file in your project, but"

	switch c.goBinaryStatus {
	case goBinaryStatusNotFound:
		return fmt.Errorf(baseMsg+" you need to install Go to use it. See https://golang.org/dl/ : %q", err)
	case goBinaryStatusTooOld:
		return fmt.Errorf(baseMsg+" you need to a newer version of Go to use it. See https://golang.org/dl/ : %w", err)
	}

	return err
}

type vendoredModule struct {
	Owner   Module

View on GitHub (pinned to 52c9bd7908)

Solutions

Run 'hugo mod tidy' to download and reconcile module dependencies.
Check the module path for typos and that it is reachable (network/proxy/credentials for private repos).
Pre-populate or vendor the module cache, or set ignoreVendor not needed: run 'hugo vendor' for offline builds.
Set imports[].ignoreConfig/avoidConfig or rely on ignoreModuleDoesNotExist only if missing modules are expected.

Example fix

// before
[[module.imports]]
path = "github.com/exmple/wrong-speling"

// after
[[module.imports]]
path = "github.com/example/correct-module"

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: ensure each imported module is fetchable
for _, imp := range cfg.Module.Imports {
    if imp.Path == "" { continue }
    if err := verifyModuleReachable(imp.Path); err != nil {
        return fmt.Errorf("module %s not reachable: %w", imp.Path, err)
    }
}

Try / catch

// in Go code that drives Hugo
err := hugoModules.Collect(ctx)
if errors.Is(err, modules.ErrNotExist) {
    // run hugo mod tidy, or skip if optional
}

Prevention

Run 'hugo mod tidy' in CI before building.
Populate the module cache or vendor deps for offline builds.
Double-check private module auth (GOPRIVATE, netrc).

When it happens

Trigger: Hugo tries to load a module import (module.imports path) that is not present in the local Go module cache and cannot be fetched; IgnoreModuleDoesNotExist is false (the default).

Common situations: Importing a private/typo'd module path; offline build with an unpopulated module cache; go.sum/go.mod referencing a module that was deleted from the remote; first build on a fresh machine without 'hugo mod tidy' having run.

Related errors

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