Untouched references suddenly trigger "REF_NOT_FOUND" error

support
1

Hi,

I am blocked by a weird issue. I started a new blog post, and when I run hugo server, I get numerous REF_NOT_FOUND errors for pages that I haven’t touched in ages:

hugo server
Watching for changes in /Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/{archetypes,content,data,layouts,static}
Watching for config changes in /Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/config/_default, /Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/go.mod
Start building sites … 
hugo v0.131.0+extended darwin/arm64 BuildDate=2024-08-02T09:03:48Z VendorInfo=brew

ERROR [en] REF_NOT_FOUND: Ref "/flow/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/flow2go/index.md:25:24": page not found
ERROR [en] REF_NOT_FOUND: Ref "/bintree": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/big-o/index.md:66:65": page not found
ERROR [en] REF_NOT_FOUND: Ref "/balancedtree/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/big-o/index.md:66:108": page not found
ERROR [en] REF_NOT_FOUND: Ref "/perceptron": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/ai-times-three/index.md:575:86": page not found
ERROR [en] REF_NOT_FOUND: Ref "/balancedtree/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/instantgo/index.md:200:202": page not found
ERROR [en] REF_NOT_FOUND: Ref "/balancedtree": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/generics/index.md:32:168": page not found
ERROR [en] REF_NOT_FOUND: Ref "/generictree": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/generics/index.md:32:233": page not found
ERROR [en] REF_NOT_FOUND: Ref "/release2": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/goman/index.md:104:62": page not found
ERROR [en] REF_NOT_FOUND: Ref "/bintree": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/generictree/index.md:43:19": page not found
ERROR [en] REF_NOT_FOUND: Ref "/balancedtree": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/generictree/index.md:43:94": page not found
ERROR [en] REF_NOT_FOUND: Ref "/awslambda/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/mantil/index.md:24:48": page not found
ERROR [en] REF_NOT_FOUND: Ref "/generictree/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/bintree/index.md:104:183": page not found
ERROR [en] REF_NOT_FOUND: Ref "/release": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/release2/index.md:26:71": page not found
ERROR [en] REF_NOT_FOUND: Ref "/goman/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/release/index.md:45:143": page not found
ERROR [en] REF_NOT_FOUND: Ref "/goman": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/release/index.md:331:9": page not found
ERROR [en] REF_NOT_FOUND: Ref "/generictree/": "/Users/christoph/Documents/Business/AppliedGo/Blog/Hugo/content/post/balancedtree/index.md:181:194": page not found
Built in 2344 ms
Error: error building site: logged 16 error(s)

An example of a failing reference:

In [this article]({{< ref "/bintree" >}}), ...

The tree of the bintree article:

content/post/bintree
├── index.md
└── media
    ├── <resources...>

I have permalinks settings in action. The relevant line from permalinks.toml:

post = "/:filename/"

So the article in content/post/bintree is available at https://<baseurl>/bintree.

So far, {{< ref "/bintree" >}} perfectly resolved to the correct URL, but now I get these errors. I searched this forum and the Web, but none of the issues around REF_NOT_FOUND seem to match this issue.

Why does Hugo error out on page references that worked earlier?

2

First I would verify that the site still builds fine with the hugo version you used before. Which one?

If it does try moving forward to find the breaking one…

There might be some subtile differences depending on the age of your old one.

One common problem is a missing trailing sladh in baseURL setting.

3

Thank you, @irkode.

I use Hugo via Homebrew, and Homebrew cannot install old versions. So I built a few Hugo versions from source:

  • v0.130.0: no change
  • v0.129.0: no change
  • v0.120.0: The number of errors halved, complaining only about references that contain a trailing slash
  • v0.110.0: Got a whole new range of errors: render of "page" failed: ... execute of template failed: ... can't evaluate field JoinPath in type interace {}. I guess I am using some newer functionality for my site
  • v0.115.0: same as v0.120.0
  • v0.112.0: more errors than with 0.115/0.120, but all 14 of them complain about references with a trailing slash, whereas in 0.131.0, only 7 of the references have a trailing slash

If the baseURL was misconfigured, I’d guess that there’d be more errors than just these cross reference errors.

I looked through the Git history of my site, to see if any possibly harmful change jumps into my face, but honestly, I have no idea what to look out for.

Worth noting that the pages that Hugo claims to be unable to find are getting created. The bintree page, for example, exists in /public/bintree after running Hugo, despite the build errors.

4

Tip: When you do things like installing multiple versions for testing, don’t install the .0 versions; use the latest in those minor versions. Many errors are solved between, e.g. v0.111.0 and v0.111.3. You might save time.

5

Do you know which version was used the last time. It should work with that one. And it maybe help our gurus to directly see the error

It’s maybe in the meta tags of your life site.

Without code it will be hard to track that down for us. If you could provide a repo I guess we could assist better.

For testing different versions i would also use binary tests. Taken the one in the middle beween working and failing. And go with @davidsneighbour in taking last minor

6

Thank you for the tip, @davidsneighbour. In my case, the latest version is the one that errors out, so any earlier version, whatever patchlevel, should be fine for bisecting my way towards the last good version.

At one point, the Hugo version was too old to render my current site properly. Between that and the current version, none of the versions I tested compiles my site with no error.

7

Unfortunately, no. The oldest version I tested is too old to compile my site. I don’t expect that I find a working version between that version and the current one.

I tried to do bisecting (the list of versions I tried is in chronological order of testing), but without any working version, I cannot bisect towards the last working version.

Maybe the reason for the errors lies indeed in some change in my site—a change too subtle to look like it would cross-references.

8

The page lookup behavior changed in v0.128.2.
https://github.com/gohugoio/hugo/releases/tag/v0.128.2

If the given logical path begins with a slash, we look for a page starting at the content root.

content/
├── post/
│   └── bintree/
│       └── index.md
└── _index.md

{{ (site.GetPage "bintree").Title }} --> Bintree
{{ (site.GetPage "bintree/").Title }} --> Bintree
{{ (site.GetPage "/bintree").Title }} --> ""
{{ (site.GetPage "/bintree/").Title }} --> ""

The trailing slash on the given path is irrelevant.

The baseURL setting is also irrelevant. And to clarify, since v0.123.0 Hugo automatically adds a trailing slash to the baseURL if it does not already exist.

1 Like
9

This seems to be in line with my setup and use of cross-references.

Content path:

content/post/bintree
├── index.md

With the permalinks setting

post = "/:filename/"

the path /post/bintree converts to the slug

/bintree

However,

{{< ref "/bintree" >}})

does not find that page.

Confirmed, the errors I get are for cross-references with and without trailing slashes.

10

The permalink setting is irrelevant. That setting affects the published path, not the logical path to the content.

11

Did that change recently? My cross-references worked fine for years, pointing to the published slug.

12

See above.

13

Confirmed. v0.127 works.

Weird that v0.120 triggered some of these errors. It’s also pre-0.128.2.

Anyway, thank you, @jmooring, for helping to track this down.

Has this breaking change been announced anywhere?

14

Although the changes are announced in the release notes, this particular bug fix was not called out as a breaking change. I’m sorry we broke your site.

15

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.