What causes "failed to decode file cache entry: %w" in gohugoio/hugo?

Clear the cache: run `hugo --gc` or delete the Hugo cache directory (e.g. $TMPDIR/hugo_cache).

failed to decode file cache entry: %w

Error message

failed to decode file cache entry: %w

What it means

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.

Source

Thrown at tpl/transform/transform.go:341

				Output:   result.Data.Output,
				Warnings: result.Header.Warnings,
			}

			buf := &bytes.Buffer{}
			enc := json.NewEncoder(buf)
			enc.SetEscapeHTML(false)
			if err := enc.Encode(e); err != nil {
				return nil, fmt.Errorf("failed to encode file cache entry: %w", err)
			}
			return hugio.NewReadSeekerNoOpCloserFromBytes(buf.Bytes()), nil
		})
		if err != nil {
			return "", err
		}

		var e fileCacheEntry
		if err := json.NewDecoder(r).Decode(&e); err != nil {
			return "", fmt.Errorf("failed to decode file cache entry: %w", err)
		}

		for _, warning := range e.Warnings {
			ns.deps.Log.Warnf("transform.ToMath: %s", warning)
		}

		return template.HTML(e.Output), err
	})
	if err != nil {
		return "", err
	}

	return v, nil
}

// For internal use.
func (ns *Namespace) Reset() {
	ns.cacheUnmarshal.Clear()

View on GitHub (pinned to 52c9bd7908)

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.

Example fix

// before — stale/corrupt cache causes decode failure
$ hugo
ERROR: failed to decode file cache entry

// after — clear cache and rebuild
$ hugo --gc
$ hugo

Defensive patterns

Strategy: fallback

Try / catch

// On decode-cache failure, clear the cache and rebuild to regenerate:
//   hugo --gc && hugo
// In Go, you can clear the misc cache programmatically before retrying.

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/19531d63241dd150. Report an issue: GitHub.