Troubleshooting and common issues

Hugo cannot download a module

Hugo Modules require Git and Go. A fresh clone downloads the versions recorded in go.mod when Hugo first builds the site, so it also requires network access. Check the local tools and verify the configured modules with:

git --version
go version
hugo mod verify

Hugo reports a checksum mismatch

If an upstream repository changes a revision that was already downloaded, Go will reject it because its content no longer matches the checksum in go.sum. Do not disable checksum verification. Instead, synchronize the affected module revision, review the resulting go.mod and go.sum changes, and commit them together:

python3 tools/sync_hugo_modules.py
hugo mod verify

Local imported content is older than upstream content

Hugo builds imported documentation from the revisions pinned in go.mod, not from another checkout on your computer. Run the Update Hugo modules workflow or the synchronization command above to select newer upstream revisions.

Hugo cannot clean its cache

The production build uses --gc, which requires a writable Hugo cache. In a restricted container or environment, select a cache directory owned by your user:

HUGO_CACHEDIR=/tmp/precice-hugo-cache hugo --gc --minify

Search results are stale

Building the site only creates public/algolia.json; it does not upload records to Algolia. Build and validate the export locally with:

npm ci
hugo --gc --minify --cleanDestinationDir --environment production
npm run algolia:index -- --dry-run

Use the Update the Algolia search index workflow to publish the validated records with the repository’s configured credentials.