gohugoio/hugo · error

module not found

Error message

module %q not found

What it means

In getAndCreateModule, after an explicit-version download (downloadModuleVersion) returned no error but a nil module. Hugo requested path@version, the call succeeded without error, yet no module object came back — so it cannot proceed. This is an unusual defensive check rather than a normal user-facing failure.

Solutions

1. Re-run the build (transient), then reproduce with `go mod download -json path@version` and check the JSON has a non-empty Dir.
2. Upgrade the Go toolchain to a version compatible with your Hugo release.
3. Report upstream to Hugo if the go command clearly returns a valid module but Hugo still sees nil.
4. Clear caches: `go clean -modcache && hugo mod clean`.

Example fix

null

// Before relying on an explicit-version download, confirm a module comes back
m, err := c.downloadModuleVersion(path, version)
if err == nil && m == nil {
  err = fmt.Errorf("module %q returned empty after download", path)
}

null

// if err == nil && m == nil { /* retry once, then report path as unresolvable */ }

When it happens

Trigger: downloadModuleVersion returns (nil, nil) — theoretically when go mod download reports success but produces a goModule with an empty Dir and no Error, which is not expected from a real toolchain. Reachable only via unusual toolchain behaviour or a future code path that returns nil without error.

Common situations: Practically not hit in normal operation; would indicate a toolchain/wrapper returning an empty-but-successful result, or a regression in downloadModuleVersion.

Related errors

• failed to decode module download result
• failed to decode modules list
• failed to download module
• failed to download module
• failed to download modules

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

Appendix: source

Thrown at modules/collect.go:287

	if moduleDir == "" {
		if requestedVersionQuery == "" {
			mod = c.gomods.GetByPath(modulePath)
			if mod != nil {
				moduleDir = mod.Dir
			}
		}

		if moduleDir == "" {
			if isProbablyModule(modulePath) {
				if requestedVersionQuery != "" {
					var err error
					mod, err = c.downloadModuleVersion(modulePath, requestedVersionQuery)
					if err != nil {
						return nil, err
					}
					if mod == nil {
						return nil, fmt.Errorf("module %q not found", modulePath)
					}
					moduleDir = mod.Dir
					versionMod = mod.Version
				} else if c.GoModulesFilename != "" {
					// See https://golang.org/ref/mod#version-queries
					// This will select the latest release-version (not beta etc.).
					const versionQuery = "upgrade"
					// Try to "go get" it and reload the module configuration.

					// Note that we cannot use c.Get for this, as that may
					// trigger a new module collection and potentially create a infinite loop.
					if err := c.get(fmt.Sprintf("%s@%s", modulePath, versionQuery)); err != nil {
						return nil, err
					}
					if err := c.loadModules(); err != nil {
						return nil, err
					}

View on GitHub (pinned to 52c9bd7908)