Hugo "REF_NOT_FOUND" ref/relref shortcode error in CI
A {{< ref >}} or {{< relref >}} shortcode references a page that Hugo cannot resolve. When refLinksErrorLevel is ERROR, this fails the build instead of emitting a warning placeholder.
What this error means
hugo fails with "REF_NOT_FOUND: Ref "X": page not found" naming the source page and the unresolved target.
hugo
ERROR REF_NOT_FOUND: Ref "setup.md": "content/docs/intro.md:14:20": page not foundCommon causes
The referenced page does not exist
The ref/relref target was renamed, moved, or misspelled, so Hugo cannot resolve it to a content page.
A wrong path relative to the page
relref resolves relative to the current page; an incorrect relative path points at no page.
How to fix it
Fix the ref target
- Read the source page and unresolved target the error names.
- Correct the ref/relref to the real content path or restore the page.
- Rebuild to confirm it resolves.
content/docs/intro.md
[Setup]({{< relref "setup.md" >}})Confirm the error level is intentional
Keeping refLinksErrorLevel = "ERROR" makes broken refs fail CI; lower it only if you accept warnings.
hugo.toml
# hugo.toml
refLinksErrorLevel = "ERROR"How to prevent it
- Use ref/relref with correct content paths.
- Update refs when renaming or moving content.
- Keep
refLinksErrorLevel = "ERROR"so broken refs fail the build.
Frequently asked questions
What causes ""REF_NOT_FOUND""?
The ref/relref target was renamed, moved, or misspelled, so Hugo cannot resolve it to a content page.
How do I fix "REF_NOT_FOUND"?
Fix the ref target
Related guides
Hugo "Error building site: failed to render pages" in CIFix Hugo "Error building site: failed to render pages" in CI - a template executed during rendering raised, o…
Hugo "module ... not found" (Hugo Modules) in CIFix Hugo "module X not found" in CI - a Hugo Module (often a theme) could not be fetched because Go was missi…
MkDocs "contains a link ... not found among documentation files" (strict) in CIFix MkDocs "contains a link to X which is not found in the documentation files" in CI - a relative link point…