{"record":{"id":"73f6c49a54951c4c","repo":"gohugoio/hugo","slug":"failed-to-download-module-s-s-w","errorCode":null,"errorMessage":"failed to download module %s@%s: %w","messagePattern":"failed to download module (.+?)@(.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/client.go","lineNumber":466,"sourceCode":"\t\tif err := json.Unmarshal(b, &cm); err == nil && cm.Dir != \"\" {\n\t\t\tif c.isDirNonEmpty(cm.Dir) {\n\t\t\t\treturn &cm, nil\n\t\t\t}\n\t\t}\n\t}\n\n\t// No valid cache, need to query.\n\targs := []string{\"mod\", \"download\", \"-json\", fmt.Sprintf(\"%s@%s\", path, version)}\n\n\tb := &bytes.Buffer{}\n\terr := c.runGo(context.Background(), b, args...)\n\tif err != nil {\n\t\t// The -json flag makes Go output error details as JSON to stdout\n\t\t// even on failure. Try to extract the error message from the JSON output.\n\t\tif jsonErr := extractGoModDownloadError(b.Bytes()); jsonErr != \"\" {\n\t\t\treturn nil, fmt.Errorf(\"failed to download module %s@%s: %s: %s\", path, version, err, jsonErr)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"failed to download module %s@%s: %w\", path, version, err)\n\t}\n\n\tjsonResult := b.Bytes()\n\n\tm := &goModule{}\n\tif err := json.NewDecoder(bytes.NewReader(jsonResult)).Decode(m); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to decode module download result: %w\", err)\n\t}\n\n\tif m.Error != nil {\n\t\treturn nil, errors.New(m.Error.Err)\n\t}\n\n\t// Cache the successful result if it has a Dir field.\n\tif m.Dir != \"\" {\n\t\t_ = c.ccfg.ModuleQueriesCache.SetBytes(cacheKey, jsonResult)\n\t}\n","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/modules/client.go#L448-L484","documentation":"Sibling of 460, also in downloadModuleVersion, but fired when extractGoModDownloadError returns an empty string — i.e. `go mod download -json` failed but produced no parseable JSON Error field. The wrapped error is the raw go-command failure (usually an exec.ExitError string from stderr). It signals an opaque go-toolchain failure that Hugo could not annotate further.","triggerScenarios":"An explicit-version module import where `go mod download -json path@version` exits non-zero with stderr that is not valid JSON or lacks the Error key — e.g. go binary crash, SIGKILL (OOM), TLS handshake error printed to stderr, or a go version that does not emit JSON errors for certain failure classes.","commonSituations":"Outdated Go binary (<1.16) producing non-JSON output, proxy returning HTML error pages instead of JSON, network resets mid-stream, go.sum verification failures printed only to stderr, or GOFLAGS/GOENV corruption making the toolchain misbehave.","solutions":["Reproduce in isolation: run the exact `go mod download -json path@version` from the Hugo working dir and read the raw stderr that Hugo did not parse.","Upgrade the Go toolchain to a current version (`go version`) since older releases emit non-JSON errors Hugo cannot parse.","If stderr shows a sum mismatch, run `go mod tidy` / `hugo mod tidy` to refresh go.sum.","For TLS/proxy HTML errors, fix GOPROXY and network egress, then `go clean -modcache` and retry."],"exampleFix":"// reproduce to see the raw error\n// (run from your project root)\ngo mod download -json github.com/x/y@v1.2.3\n// then act on the stderr shown, e.g. update sums:\nhugo mod tidy","handlingStrategy":"validation","validationCode":"// Probe the exact command Hugo will run and inspect raw stderr\nimport \"os/exec\"\n\nfunc probeDownload(path, version string) error {\n  cmd := exec.Command(\"go\", \"mod\", \"download\", \"-json\", path+\"@\"+version)\n  var stderr bytes.Buffer\n  cmd.Stderr = &stderr\n  if err := cmd.Run(); err != nil {\n    if strings.TrimSpace(stderr.String()) != \"\" {\n      return fmt.Errorf(\"non-json go error: %s\", stderr.String())\n    }\n    return err\n  }\n  return nil\n}","typeGuard":"null","tryCatchPattern":"// Wrap downloadModuleVersion callers:\n// m, err := c.downloadModuleVersion(p, v)\n// if err != nil && !strings.Contains(err.Error(), \"-json\") {\n//   // likely opaque go failure -> ask user to run go mod download manually\n// }","preventionTips":["Keep Go on a supported, current version.","Avoid shell rc files that print to stdout when go is invoked.","CI: pre-warm the module cache so downloads during Hugo are rare.","Reproduce any opaque failure with the exact `go mod download` before debugging Hugo."],"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"}