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

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.

hugo

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

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

.github/workflows/docs.yml

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

hugo.toml

[[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.