gohugoio/hugo · error

failed to list modules

Error message

failed to list modules: %w

What it means

listAndDecodeModules runs `go list -m -json [all]` to enumerate the resolved module graph; if that command exits non-zero, this wraps the failure. `go list` is how Hugo learns each module's Dir/Version/Replace, so a failure here means Hugo cannot construct the module set at all.

Solutions

1. Run `go list -m all` from the project root to see the exact go-side error.
2. Check go.mod `replace` directives point at existing local paths; fix or remove stale ones.
3. Run `hugo mod tidy` to reconcile go.mod/go.sum with the actual graph.
4. If vendoring, regenerate the vendor dir: `hugo mod vendor` and ensure GOFLAGS is consistent.

Example fix

// before: replace target deleted
require github.com/x/y v1.0.0
replace github.com/x/y => ../y-old
// after: remove or repoint the replace, then
hugo mod tidy

// Validate the module graph resolves before Hugo
func ensureModuleList(projectDir string) error {
  cmd := exec.Command("go", "list", "-m", "all")
  cmd.Dir = projectDir
  if out, err := cmd.CombinedOutput(); err != nil {
    return fmt.Errorf("go list -m all: %s", out)
  }
  return nil
}

null

null

When it happens

Trigger: Any module-enabled project where `go list -m -json all` fails — unresolved imports, replace directives pointing at missing local paths, go.mod syntax errors, or a go.sum missing entries that list requires.

Common situations: A `replace` directive in go.mod pointing to a directory that was deleted/moved, a module import path typo that go list cannot resolve, inconsistent go.mod after a merge, or GOFLAGS=-mod=vendor with a stale vendor/ dir.

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/8e7a7309c5ec6189. Report an issue: GitHub.

Appendix: 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 52c9bd7908)