{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/modules/client.go#L493-L529","documentation":"Returned by listGoMods' downloadModules helper when the bulk `go mod download` (all modules in go.mod) fails before Hugo lists modules. Hugo needs all imports fetched into the module cache before it can resolve mounts and themes, so a failure here aborts the module graph build.","triggerScenarios":"Any `hugo` build/serve on a module-enabled site where `go mod download` exits non-zero: unreachable proxy, missing go.sum entries, checksum mismatch against sum.golang.org, or a module in go.mod that no longer resolves.","commonSituations":"Fresh clone without network access, CI runners behind proxies, go.sum out of sync after hand-editing go.mod, upstream theme repo deleted or retagged.","solutions":["Run `hugo mod tidy` to sync go.mod/go.sum.","Check connectivity to GOPROXY, or set GOPROXY=direct / a mirror.","For private modules, configure GOPRIVATE and credentials.","Use `hugo mod vendor` so builds don't need network."],"exampleFix":"# before\nhugo build   # fails offline\n# after\nhugo mod vendor\nhugo build   # uses _vendor, no network","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := client.Download(); err != nil {\n    if isTransient(err) {\n        // bounded retry with backoff for bulk download\n    } else {\n        return fmt.Errorf(\"module download failed; run 'hugo mod verify' or clear cache with 'hugo mod clean': %w\", err)\n    }\n}","preventionTips":["Run 'hugo mod tidy' first so the module graph is consistent before bulk download","Cache GOMODCACHE across CI runs to minimize network exposure","On persistent failure, 'hugo mod clean' then re-download rather than retrying against a corrupt cache"],"tags":["go-modules","hugo-mod","download","network","ci"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}