{"record":{"id":"fb7275f6f82d7878","repo":"gohugoio/hugo","slug":"failed-to-download-modules-w","errorCode":null,"errorMessage":"failed to download modules: %w","messagePattern":"failed to download modules: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/client.go","lineNumber":511,"sourceCode":"\t}\n\tdefer f.Close()\n\t// Read just one entry to check if directory is non-empty.\n\t_, err = f.Readdirnames(1)\n\treturn err == nil\n}\n\nfunc (c *Client) listGoMods() (goModules, error) {\n\tif c.GoModulesFilename == \"\" || !c.moduleConfig.hasModuleImport() {\n\t\treturn nil, nil\n\t}\n\n\tdownloadModules := func(modules ...string) error {\n\t\targs := []string{\"mod\", \"download\"}\n\t\targs = append(args, modules...)\n\t\tout := io.Discard\n\t\terr := c.runGo(context.Background(), out, args...)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to download modules: %w\", err)\n\t\t}\n\t\treturn nil\n\t}\n\n\tif err := downloadModules(); err != nil {\n\t\treturn nil, err\n\t}\n\n\tlistAndDecodeModules := func(handle func(m *goModule) error, modules ...string) error {\n\t\tb := &bytes.Buffer{}\n\t\targs := []string{\"list\", \"-m\", \"-json\"}\n\t\tif len(modules) > 0 {\n\t\t\targs = append(args, modules...)\n\t\t} else {\n\t\t\targs = append(args, \"all\")\n\t\t}\n\t\terr := c.runGo(context.Background(), b, args...)\n\t\tif err != nil {","sourceCodeStart":493,"sourceCodeEnd":529,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/modules/client.go#L493-L529","documentation":"From the downloadModules closure inside listGoMods: a bare `go mod download` (no -json, no explicit modules) exited non-zero, so Hugo aborts the entire module graph load. This is the bulk pre-fetch that precedes `go list`, so any failure to fetch the module set surfaces here wrapped over the raw go error.","triggerScenarios":"Any project with at least one module import (moduleConfig.hasModuleImport() true and GoModulesFilename set) where `go mod download` fails — network, auth, sum, or version-resolution errors during the initial bulk download.","commonSituations":"First build on a new machine with cold module cache, private modules without GOPRIVATE, broken go.sum after a dependency yanked a version, proxy outage, or GOFLAGS=-mod=readonly blocking required downloads.","solutions":["Run `hugo mod tidy` (or `go mod download`) in the project to surface and fix the underlying go error, then rebuild.","For private repos set GOPRIVATE and ensure the VCS credentials/SSH config work: `go env -w GOPRIVATE=github.com/yourorg/*`.","If go.sum is stale/corrupt, delete go.sum and regenerate with `hugo mod tidy`.","Verify network egress to proxy.golang.org (or your GOPROXY mirror) and that GOFLAGS is not pinned to -mod=vendor/-mod=readonly incorrectly."],"exampleFix":"// before: cold cache + private module, download fails\n// after: tidy regenerates sums and pulls modules\nhugo mod tidy\nhugo","handlingStrategy":"validation","validationCode":"// Pre-flight: bulk download must succeed before Hugo runs\nfunc ensureModulesDownloaded(projectDir string) error {\n  cmd := exec.Command(\"go\", \"mod\", \"download\")\n  cmd.Dir = projectDir\n  if out, err := cmd.CombinedOutput(); err != nil {\n    return fmt.Errorf(\"go mod download: %s\", out)\n  }\n  return nil\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Run `hugo mod tidy` in CI before the build step.","Set GOPRIVATE/GOPROXY consistently across dev and CI.","Commit a correct go.sum and avoid GOFLAGS=-mod=readonly unless vendored.","Pre-warm caches in Docker builds."],"tags":["modules","go-toolchain","network","hugo-module"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}