{"record":{"id":"19531d63241dd150","repo":"gohugoio/hugo","slug":"failed-to-decode-file-cache-entry-w","errorCode":null,"errorMessage":"failed to decode file cache entry: %w","messagePattern":"failed to decode file cache entry: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/transform/transform.go","lineNumber":341,"sourceCode":"\t\t\t\tOutput:   result.Data.Output,\n\t\t\t\tWarnings: result.Header.Warnings,\n\t\t\t}\n\n\t\t\tbuf := &bytes.Buffer{}\n\t\t\tenc := json.NewEncoder(buf)\n\t\t\tenc.SetEscapeHTML(false)\n\t\t\tif err := enc.Encode(e); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to encode file cache entry: %w\", err)\n\t\t\t}\n\t\t\treturn hugio.NewReadSeekerNoOpCloserFromBytes(buf.Bytes()), nil\n\t\t})\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\n\t\tvar e fileCacheEntry\n\t\tif err := json.NewDecoder(r).Decode(&e); err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to decode file cache entry: %w\", err)\n\t\t}\n\n\t\tfor _, warning := range e.Warnings {\n\t\t\tns.deps.Log.Warnf(\"transform.ToMath: %s\", warning)\n\t\t}\n\n\t\treturn template.HTML(e.Output), err\n\t})\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\treturn v, nil\n}\n\n// For internal use.\nfunc (ns *Namespace) Reset() {\n\tns.cacheUnmarshal.Clear()","sourceCodeStart":323,"sourceCodeEnd":359,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/tpl/transform/transform.go#L323-L359","documentation":"When transform.ToMath finds a cached entry, it JSON-decodes the cached file back into fileCacheEntry (transform.go:339-342). If the cached file is corrupt, truncated, or from an incompatible cache version, decoding fails and the error wraps the json.Decode failure. The cache key embeds a version prefix (fileCacheEntryVersion = \"v1\") but stale/corrupt files can still occur.","triggerScenarios":"A cache file under the tomath/v1/... path is corrupt or partially written — e.g. a previous build was killed mid-write, the filesystem returned garbage, or a Hugo version change altered the entry shape without a version bump.","commonSituations":"Interrupted `hugo` build leaving a half-written cache file; manual editing/corruption of the cache dir; switching between very old and new Hugo versions sharing a cache directory; disk issues.","solutions":["Clear the cache: run `hugo --gc` or delete the Hugo cache directory (e.g. $TMPDIR/hugo_cache).","Re-run the build — a fresh entry will be written.","If recurring, check for disk/filesystem errors or concurrent builds writing the same cache."],"exampleFix":"// before — stale/corrupt cache causes decode failure\n$ hugo\nERROR: failed to decode file cache entry\n\n// after — clear cache and rebuild\n$ hugo --gc\n$ hugo","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"// On decode-cache failure, clear the cache and rebuild to regenerate:\n//   hugo --gc && hugo\n// In Go, you can clear the misc cache programmatically before retrying.","preventionTips":["Run `hugo --gc` after interrupted builds or version upgrades.","Don't share a cache directory across incompatible Hugo versions.","Investigate disk/filesystem errors if corruption recurs."],"tags":["transform","tomath","cache","json","decoding","corruption"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}