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

Run `hugo mod tidy` to repair go.mod/go.sum.

failed to list modules: %w

Error message

failed to list modules: %w

What it means

Returned when `go list -m -json all` (or for specific modules) fails while Hugo enumerates the module graph. Hugo relies on this listing to map imports to on-disk directories; failure means the module graph can't be built.

Source

Thrown at modules/client.go:530

		}
		return nil
	}

	if err := downloadModules(); err != nil {
		return nil, err
	}

	listAndDecodeModules := func(handle func(m *goModule) error, modules ...string) error {
		b := &bytes.Buffer{}
		args := []string{"list", "-m", "-json"}
		if len(modules) > 0 {
			args = append(args, modules...)
		} else {
			args = append(args, "all")
		}
		err := c.runGo(context.Background(), b, args...)
		if err != nil {
			return fmt.Errorf("failed to list modules: %w", err)
		}

		dec := json.NewDecoder(b)
		for {
			m := &goModule{}
			if err := dec.Decode(m); err != nil {
				if err == io.EOF {
					break
				}
				return fmt.Errorf("failed to decode modules list: %w", err)
			}

			if err := handle(m); err != nil {
				return err
			}
		}
		return nil
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Run `hugo mod tidy` to repair go.mod/go.sum.
Run `go list -m -json all` manually in the site dir to see the raw error.
Set GOWORK=off or remove a stray go.work affecting the site directory.
Ensure the installed Go version satisfies the go directive in go.mod.

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure a module file exists so 'go list -m' has something to list
if _, err := os.Stat(filepath.Join(workingDir, "go.mod")); errors.Is(err, os.ErrNotExist) {
    // run Init first or skip module listing
}

Try / catch

mods, err := client.List()
if err != nil {
    return fmt.Errorf("listing modules failed; verify go.mod is valid ('go mod verify'): %w", err)
}

Prevention

Ensure go.mod exists and parses before invoking list operations
Keep go.sum in sync (run 'hugo mod tidy' after editing module config)
Don't hand-edit go.mod entries to versions that don't exist

When it happens

Trigger: `go list -m -json [all|mods...]` exiting non-zero: inconsistent go.mod (missing requires), Go workspace/GOFLAGS interference, missing go.sum entries with GOFLAGS=-mod=readonly, or a go version that can't parse the go.mod go directive.

Common situations: Hand-edited go.mod, a go.work file in a parent directory pulling the site into an unrelated workspace, Go upgraded/downgraded between builds.

Related errors

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