Local development troubleshooting
Note: If these troubleshooting steps do not resolve your problem, ask for help in #handbook on Slack.
Run all recovery commands on this page from your handbook repository root. Stop any running preview before retrying.
2026-09-14: Hugo 0.166.0 required
The Hugo and Docsy upgrade is merged across all three projects and requires Hugo Extended 0.166.0. See the upgrade rollout issue #51 for the strategy, testing, and performance findings. The merged upgrade MRs are:
- Docsy GitLab !329: upgrade the shared theme to Docsy 0.17.0.
- Internal handbook !9015: integrate the theme and Hugo upgrade.
- Public handbook !21074: integrate the theme and Hugo upgrade.
Use the version pinned in your checkout’s .tool-versions. Older branches may
still pin an earlier version.
Upgrade Hugo or refresh the environment
Use the recovery commands for your workflow after updating your checkout.
The preview commands below reinstall npm dependencies, remove generated public/
output, synchronize data, and start Hugo. You do not need to run npm ci or
make clean separately.
Local installation
If you use mise, install the versions pinned in .tool-versions, then restart:
mise install
hugo version
make view
If you installed Hugo without mise, update Hugo Extended using your existing
installation method to match .tool-versions, then run:
hugo version
make view
make view installs npm dependencies but does not upgrade your local Hugo.
If the version is still wrong, compare the executable selected by your shell with mise:
command -v hugo
hugo version
mise exec -- hugo version
For shell setup, follow activate mise.
If you use mise shims, mise reshim can refresh them. As a diagnostic fallback,
mise exec -- make view selects mise’s tools explicitly.
Docker Compose
Docker provides the pinned Hugo version and installs dependencies inside the container. You do not need Hugo, Node.js, npm, or mise installed on your host. Use the updated checkout’s Compose configuration to refresh the preview:
docker compose down
docker compose pull hugo
docker compose up --force-recreate
This recreates the container and reinstalls its npm dependencies while keeping the dependency and build-cache volumes. If the version is still wrong, check it inside the container:
docker compose run --rm hugo hugo version
Compare the output with .tool-versions and check any Compose override files
that might select an older image. Upgrading Hugo on the host does not change
Hugo inside the container.
Docker without Compose
Stop the existing preview and start a new container with the Makefile’s pinned image:
make docker-view
This installs dependencies inside the container automatically. If you previously
set HUGO_IMAGE, remove or update that override. For a manual docker run command,
update the image tag to match .tool-versions and start a new container using the
manual Docker instructions.
Incompatible Hugo version or template data errors
An older Hugo version can report:
WARN Module "project" is not compatible with this Hugo version: Min 0.166.0 extended
Or a page, partial, or shortcode can fail to render with:
can't evaluate field Data in type interface {}
The upgraded theme uses hugo.Data,
which was introduced in Hugo 0.156.0. Hugo 0.155.0 and earlier cannot evaluate
this function. The first error encountered depends on which template runs first.
These messages were reproduced with
Hugo 0.151.0 in a minimal site using the new version requirement and data function.
Follow upgrade Hugo or refresh the environment for your local or Docker workflow.
Hugo is missing or the wrong version runs
If you see hugo: command not found, or Hugo still reports the old version,
follow the local installation checks when running on your host.
For a Docker preview, use the Docker Compose refresh or Docker without Compose. A missing Hugo executable on the host does not affect these workflows. If Hugo is missing inside the container, check that you are using the repository’s configured image.
Missing Sass or npm dependencies
Errors about a missing Dart Sass compiler, PostCSS, or stylesheet imports can mean that npm dependencies are missing or their executables are unavailable to Hugo. Docsy 0.17.0 requires Dart Sass; upgrading Hugo alone does not install it.
For example, a missing compiler can produce these error fragments (paths vary):
TOCSS-DART: failed to transform "/test.scss" (text/x-scss).
You need to install Dart Sass
Hugo may also append this feature is not available in your current Hugo version.
In this case, check both the Hugo version and the Sass installation. The example
above was reproduced with Hugo 0.164.0 and no Sass executable on PATH.
Follow upgrade Hugo or refresh the environment. Both the local Makefile and Docker preview reinstall npm dependencies and expose the Sass and PostCSS executables automatically. Docker users do not need to install these tools on the host.
The same refresh applies if Sass compilation fails with unexpected EOF.
The npm installation script rebuilds sass-embedded so the sass executable uses
the embedded compiler. See theme dependency maintenance.
For direct Hugo commands outside the Makefile, follow the manual Hugo setup.
Permission denied when copying static files
A previous build can leave files in public/ that cause errors such as:
Error: error copying static files: open /path/to/handbook/public/webfonts/fa-solid-900.ttf: permission denied
Use the environment refresh for your workflow.
Its preview command removes generated public/ output before building again;
source content is preserved.
If cleanup also fails with permission errors, check the ownership and permissions
of public/. Recreating a container does not reset ownership of files in the
mounted checkout.
Use a container for the preview
Follow the Docker Compose workflow to avoid managing Hugo and npm tools locally. See running the handbook in Docker for initial setup and the manual Docker fallback.
0cc4a814)
