Verify Hugo Module Dependencies Before a Build

hugo mod verify checks that Hugo's cached module dependencies still match what was originally downloaded, and it is read-only by default. It reports a failure if a dependency has changed rather than fixing anything itself. Allow about ten minutes, plus time to investigate a failed check, using Hugo 0.123.7 from the installed hugo package.

1. Confirm the Hugo version and project

Run the check from the Hugo project you intend to build, or point Hugo at that project with --source. This is an ordinary, unprivileged check: it does not need sudo.

$ command -v hugo
/usr/bin/hugo
$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ cd /path/to/site

Hugo resolves the module configuration, vendor directory and Go module data relative to the project it loads, so check the working directory before proceeding. A successful verification of one site says nothing about another site's cache.

$ hugo mod verify --source /path/to/site
$ printf 'exit status: %s\n' "$?"
exit status: 0

2. Run the normal verification

From the project root, run:

$ hugo mod verify
$ printf 'exit status: %s\n' "$?"
exit status: 0

It normally prints nothing when the check succeeds. The useful result is the exit status: Hugo is checking dependencies already in its local downloaded source cache, not fetching a fresh copy to compare against. A zero status means verification completed successfully for the module view Hugo loaded.

The cache sits beneath Hugo's configured cache directory by default. If your build uses a non-default cache, point verification at the same location:

$ hugo mod verify --cacheDir /var/cache/hugo
$ printf 'exit status: %s\n' "$?"
exit status: 0

Use the cache path from the build configuration, not a convenient temporary directory. Checking a different cache can give a misleading result, or fail outright because the required module sources simply aren't there.

3. Interpret a failed check

A non-zero status means Hugo found a dependency whose cached contents no longer match the recorded download state, or it couldn't load the project and its modules at all. Capture the full diagnostic output and status before changing anything:

$ hugo mod verify 2>hugo-verify.err
$ status=$?
$ cat hugo-verify.err
$ printf 'exit status: %s\n' "$status"
exit status: 1

The error text may point at a specific module or a cache problem. Also check that you're in the intended project, that the configured cache is readable, and that the project's go.mod and go.sum haven't changed unexpectedly.

If the project uses vendored modules, work out which source Hugo is reading first. Hugo gives precedence to a _vendor directory unless told to ignore matching vendor paths, then falls back to Go modules and theme directories. Verifying a cache does not prove that a separately committed _vendor tree is trustworthy.

4. Remove only failed cache entries when justified

The --clean option changes state: it deletes module-cache entries that fail verification so Hugo can fetch them again the next time the module is resolved. That means network access, altered build inputs, and lost evidence you might need for an investigation, so it is not the first response to an unexpected failure.

Preserve the diagnostic and confirm the project and cache are the intended ones before using it:

$ hugo mod verify --clean
$ printf 'exit status: %s\n' "$?"
exit status: 0

5. Verify again before building

After a deliberate recovery, run the same command without changing paths so the result is directly comparable:

$ hugo mod verify
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ hugo

Keep verification and build in the same environment. If you used --source, --cacheDir, a theme selection or another project-specific setting during the check, use the equivalent settings for the build. Verification only protects the cached dependency contents; it does not test your templates, content, Go toolchain, network availability or the complete build output.