Hugo "module ... not found" (Hugo Modules) in CI

By Kaveh Alemi·Latchkey

Hugo Modules use Go to fetch dependencies declared in go.mod / hugo.toml. A missing Go toolchain, a wrong module path, or an unfetched module makes Hugo report the module as not found.

What this error means

hugo fails with "Error: module 'X' not found; either add it as a Hugo Module or store it in ..." or "failed to download modules", before rendering.

Error: module "github.com/acme/hugo-theme" not found; either add it as a Hugo Module
or store it in "themes".

Common causes

Go is not installed on the runner

Hugo Modules require the Go toolchain to download modules; without Go, fetching fails and the module is reported missing.

A wrong module path or unfetched module

The import path in go.mod / config is incorrect, or hugo mod get was never run, so the module cannot be resolved.

How to fix it

Install Go and fetch modules

1. Set up Go in CI before the Hugo build.
2. Run hugo mod get (or hugo mod tidy) to download modules.
3. Rebuild.

- uses: actions/setup-go@v5
  with:
    go-version: 'stable'
- run: hugo mod get -u
- run: hugo --minify

Fix the module import path

Correct the module path in go.mod / hugo.toml so it matches the real repository.

[[module.imports]]
path = "github.com/acme/hugo-theme"

How to prevent it

• Install Go in CI when using Hugo Modules.
• Run hugo mod get before building.
• Keep module import paths correct and tidy go.mod.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation