{"record":{"id":"4f11829b4ae7b0db","repo":"gohugoio/hugo","slug":"verifying-s-s-checksum-mismatch-s-s","errorCode":null,"errorMessage":"verifying %s@%s: checksum mismatch: %s != %s","messagePattern":"verifying (.+?)@(.+?): checksum mismatch: (.+?) != (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/client.go","lineNumber":636,"sourceCode":"\t\t\tsums = append(sums, modSum{pathVersionKey: pathVersionKey{path: m.Path(), version: m.Version()}, sum: m.Sum()})\n\t\t}\n\t}\n\n\t// Read the existing sums.\n\texistingSums, err := c.readModSumFile(hugoDirectSumFilename)\n\tif err != nil {\n\t\treturn err\n\t}\n\tif len(sums) == 0 && len(existingSums) == 0 {\n\t\t// Nothing to do.\n\t\treturn nil\n\t}\n\n\tdirty := len(sums) != len(existingSums)\n\tfor _, s1 := range sums {\n\t\tif s2, ok := existingSums[s1.pathVersionKey]; ok {\n\t\t\tif s1.sum != s2 {\n\t\t\t\treturn fmt.Errorf(\"verifying %s@%s: checksum mismatch: %s != %s\", s1.path, s1.version, s1.sum, s2)\n\t\t\t}\n\t\t} else if !dirty {\n\t\t\tdirty = true\n\t\t}\n\t}\n\tif !dirty {\n\t\t// Nothing changed.\n\t\treturn nil\n\t}\n\n\t// Write the sums file.\n\t// First sort the sums for reproducible output.\n\tsort.Slice(sums, func(i, j int) bool {\n\t\tpvi, pvj := sums[i].pathVersionKey, sums[j].pathVersionKey\n\t\treturn pvi.path < pvj.path || (pvi.path == pvj.path && pvi.version < pvj.version)\n\t})\n\n\tf, err := c.fs.OpenFile(filepath.Join(c.ccfg.WorkingDir, hugoDirectSumFilename), os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o666)","sourceCodeStart":618,"sourceCodeEnd":654,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/modules/client.go#L618-L654","documentation":"Hugo maintains its own hugo.direct.sum file recording content hashes of modules it directly manages. During writeHugoDirectSum it compares freshly-computed sums against the stored ones and aborts if a path@version's hash changed — a guard against silent content drift under a pinned version. The mismatch shows the new vs stored hash.","triggerScenarios":"A module whose on-disk content changed while its declared path@version stayed identical — e.g. a local replace edited after first build, a force-pushed git tag re-downloaded into a dirty cache, or a hand-edited module dir. writeHugoDirectSum runs at the end of module collection.","commonSituations":"Developing a theme via local replace and editing files, CI caching a module across a re-publish of the same tag, a re-pulled module whose dependency changed, or a stale hugo.direct.sum checked into git that conflicts with the current tree.","solutions":["If the change is intentional (you edited the module), delete the stale sum file: `rm _vendor/hugo.direct.sum` or the project's hugo.direct.sum and rebuild so it regenerates.","For local replace development, prefer editing then `hugo mod tidy` so sums refresh.","If the module was re-published under the same tag (bad upstream practice), `go clean -modcache && hugo mod clean` to force a clean re-download.","If hugo.direct.sum is checked into git and conflicting, commit the updated sum or remove it from version control."],"exampleFix":"// before: checksum mismatch blocks build\n// after: let Hugo regenerate the direct sum file\nrm -f hugo.direct.sum _vendor/hugo.direct.sum\nhugo","handlingStrategy":"validation","validationCode":"// Before building, drop a stale direct sum if the module tree was edited\nfunc refreshDirectSumIfDirty(repoRoot string) error {\n  sum := filepath.Join(repoRoot, \"hugo.direct.sum\")\n  if _, err := os.Stat(sum); err == nil {\n    // let hugo regenerate it rather than trust a stale hash\n    return os.Remove(sum)\n  }\n  return nil\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["During local module development, remove hugo.direct.sum after edits.","Do not check a stale hugo.direct.sum into git across module re-publishes.","Treat re-published tags as broken; pin a fresh version.","Use `hugo mod tidy` after modifying replaced modules."],"tags":["modules","checksum","hugo-module","caching"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}