gohugoio/hugo · error

module does not exist

Error message

module does not exist

What it means

ErrNotExist is the sentinel defined in modules/collect.go:49 and returned by the module collector when a referenced/imported module cannot be found in the module graph. Collect/collect use it to signal a missing module dependency during site setup.

Source

Thrown at modules/collect.go:49

	"github.com/gobwas/glob"
	"github.com/gohugoio/hugo/common/herrors"
	"github.com/gohugoio/hugo/common/hmaps"
	"github.com/gohugoio/hugo/common/loggers"
	"github.com/gohugoio/hugo/common/paths"
	"github.com/gohugoio/hugo/common/version"
	"golang.org/x/mod/module"

	"github.com/spf13/cast"

	"github.com/gohugoio/hugo/parser/metadecoders"

	"github.com/gohugoio/hugo/hugofs/files"

	"github.com/gohugoio/hugo/config"
	"github.com/spf13/afero"
)

var ErrNotExist = errors.New("module does not exist")

const vendorModulesFilename = "modules.txt"

func (h *Client) Collect() (ModulesConfig, error) {
	mc, coll := h.collect(true)
	if coll.err != nil {
		return mc, coll.err
	}

	if err := (&mc).setActiveMods(h.logger); err != nil {
		return mc, err
	}

	if h.ccfg.HookBeforeFinalize != nil {
		if err := h.ccfg.HookBeforeFinalize(&mc); err != nil {
			return mc, err
		}
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Verify the module path is correct and the module exists (check the upstream repo / proxy).
2. Run `hugo mod get <path>` (or `go mod download`) to fetch it explicitly.
3. If vendoring, ensure _vendor/modules.txt lists the module and its files are present.
4. For local development, add a replace directive pointing at the local checkout.

Example fix

// before
[[module.imports]]
path = "github.com/x/mising-theme"
// after
path = "github.com/x/missing-theme"

// Resolve the module before relying on it.
// hugo mod get -- <path>  (or go mod download <path>)

// Distinguish missing-module from other collection errors.
// if errors.Is(err, modules.ErrNotExist) { /* fetch or remove import */ }

When it happens

Trigger: Importing a Hugo module (in hugo.toml [[module.imports]] or hugo.mod) that is neither vendored nor downloadable, or referencing a module path that does not resolve to any Go module. Surfaced during module collection at the start of a build.

Common situations: A theme/module path typo, a module not yet published, a missing `go mod download` for a local replace, or vendoring that omitted the module from _vendor/modules.txt.

Related errors

• invalid module config for %q: both source and target must be
• failed to load modules: %w
• failed to create config from modules config: %w
• failed to init config: %w
• could not determine content directory for %q

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