Direct answer
Hugo’s data file cache in resources/_gen uses a cache key made from the absolute file path and the file’s last‑modification timestamp (mtime). If the internal structure of a YAML, JSON or TOML data file changes but its mtime stays the same, Hugo reuses the cached parsed representation and serves stale data. As of Hugo 0.112.0 through the current 0.12x series there is no configuration option or build flag that enables content‑hash‑based or schema‑aware invalidation for data files. The --ignoreCache flag bypasses the cache entirely for a single build but does not change the invalidation rule.
Confirmed facts
- The cache key is built from file path + mtime (see
hugolib/datafiles.go, function newDataFileCache).
- Hugo’s server file watcher triggers rebuilds on write events, so active development usually picks up schema changes. The stale‑cache problem shows up in CI/CD pipelines, git‑based deployments, or any workflow that restores timestamps.
- No
cacheKey, watchDataFiles or similar setting exists in hugo.yaml or the CLI to switch to content‑based invalidation.
Likely explanation
The limitation stems from the cache key design: Hugo does not hash the file contents when deciding whether a cached parse is still valid. Therefore any change that does not update the mtime is invisible to the cache.
Steps to address
- Update the mtime of data files before building – e.g., add a pre‑build step:
find data -type f -exec touch {} + (or touch data/**/* in a script). This forces Hugo to re‑parse the files.
- If touching files is not feasible, use
hugo --ignoreCache for the build. Build time grows proportionally to the number and size of data files; it is not a drop‑in replacement for proper invalidation.
- As a template‑only workaround you can compute a content hash (e.g.,
{{ .Resources.Get \"data/file.yml\" | hash }}) and use it to bust downstream template caches, but this does not invalidate the underlying data‑file cache.
One diagnostic detail needed
Are you observing this behavior in CI/CD (GitHub Actions, GitLab CI, Netlify, etc.) or during local hugo server development? The answer changes whether a pre‑build touch step or --ignoreCache is the pragmatic fix, and whether filesystem mtime granularity (e.g., NFS, S3‑backed mounts) is a factor.
hugo