`hugo server` fails local build with many `REF_NOT_FOUND`

[jbw976]

What's Wrong?

Running hugo server locally reports a number of issues for REF_NOT_FOUND. This was discovered during the v2.4 release process #1135, but it appears to be reproducible on main before the v2.4 release also.

Errors:

ERROR [en] REF_NOT_FOUND: Ref "/latest/packages": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/cli/master/get-started/get-started-with-control-plane-projects.md:131:23": page not found
ERROR [en] REF_NOT_FOUND: Ref "/latest/packages/configurations/": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/cli/master/get-started/get-started-with-control-plane-projects.md:1:1": page not found
ERROR [en] REF_NOT_FOUND: Ref "/latest/packages": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/cli/v2.3/get-started/get-started-with-control-plane-projects.md:131:23": page not found
ERROR [en] REF_NOT_FOUND: Ref "/latest/packages": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/cli/v2.4/get-started/get-started-with-control-plane-projects.md:131:23": page not found
ERROR [en] REF_NOT_FOUND: Ref "/latest/packages/configurations/": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/cli/v2.3/get-started/get-started-with-control-plane-projects.md:1:1": page not found
ERROR [en] REF_NOT_FOUND: Ref "/latest/packages/configurations/": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/cli/v2.4/get-started/get-started-with-control-plane-projects.md:1:1": page not found
ERROR [en] REF_NOT_FOUND: Ref "/cli/latest/get-started/get-started-with-control-plane-projects": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/master/get-started/get-started-with-control-plane-projects.md:10:25": page not found
ERROR [en] REF_NOT_FOUND: Ref "/cli/latest/get-started/get-started-with-control-plane-projects": "/Users/jared/dev/go/src/github.com/crossplane/docs/content/v2.3/get-started/get-started-with-control-plane-projects.md:10:25": page not found

ERROR error building site: logged 8 error(s)

They all seem to be related to links with /latest/ either to or from the CLI docs.

hugo version output:

hugo v0.162.1-bba860e3eda3091efe8c6d1a96bc49a29ad2d5f6+extended darwin/arm64 BuildDate=2026-05-28T17:40:44Z VendorInfo=gohugoio

[haarchri]

wonder if this is only a local issue ... as per netlify_build.sh we copy for example v2.4 → content/latest and cli/v2.4 → content/cli/latest before running Hugo, so these refs resolve and the deployed site works... wdyt ?

[jbw976]

do you think that means that instead of the contribution guide saying to run bare hugo server, we should have a local_build.sh script or something that does the copy then invokes hugo server too? 🤔