😣 Troubleshooting

Some common questions and answers are listed below.

Still need help? Join the Discord to chat live with the community.

Changes do not show on my site

GitHub Pages

If you deployed your site to GitHub Pages, go to your GitHub repository in your web browser and click the Actions tab at the top of the page.

If there is an amber progress indicator, GitHub is currently updating your site.

If there is a red cross, click on the failed deploy and check the error message. You can either revert the change which broke the site, or consider addressing the issue.

Netlify

If you deployed your site to Netlify, login to Netlify and check the status of the latest deploy in the Deploys tab for your site.

If there is a progress indicator, Netlify is currently updating your site.

If there is a red cross, click on the failed deploy and check the error message. You can either revert the change which broke the site, or consider addressing the issue.

Common Causes

Usually the cause is invalid YAML syntax in a configuration file or front matter that you were editing.

You can learn more about YAML syntax here and paste the YAML config file or page front matter you were editing into an online YAML validator to get hints.

Delete Cache

Alternatively, changes may not show immediately in your web browser if your browser cached the earlier version. Delete your web browser’s cache in your browser’s settings or open an Incognito Window to force your browser to fetch a fresh copy of the site.

Still need help?

Join the Discord to chat live with the Hugo Blox community.

Remember to post the error message (such as from the deploy log in GitHub/Netlify) and link to your GitHub repository.

Error: failed to resolve output format

Cause 1: Hugo’s Cache

Users report a commonly occurring Hugo issue with the integrity of the modules cache. Consider upvoting and commenting on the issue to show the Hugo team that you are also affected.

To resolve this Hugo issue, either:

(A) Manually delete Hugo’s default cache folder and re-run Hugo. Hugo’s cache folder defaults to $TMPDIR/hugo_cache/ on Mac/Linux and %TMP%\hugo_cache\ on Windows.

Or, (B) Set a custom Hugo cache folder when you run Hugo, for example: hugo server --cacheDir ./cache/ where ./cache/ is the path of a temporary folder to create. Then you can easily locate and delete Hugo’s cache folder should you experience this issue.

Note: usually hugo mod clean --all should delete Hugo’s cache, however, users report a Hugo bug running the command in this situation. You can provide your feedback on the Hugo issues.

Cause 2: Missing Hugo Module

Currently, Hugo does not automatically remove the module’s associated output from your outputs in hugo.yaml when you unload a module.

For example, if you are not using the module for Netlify headers and redirects, those outputs must be manually removed from your outputs config or Hugo will error that you are trying to output something from a module that isn’t loaded.

Otherwise, if you require the output mentioned in the error, you need to load the module which provides that output. For Netlify headers and redirects, the Netlify module (github.com/HugoBlox/hugo-blox-builder/modules/blox-plugin-netlify) is required.

Error: File “not found” or “failed to extract”

Seeing an error similar to failed to extract shortcode…not found when editing a site you downloaded?

The error appears when Hugo cannot find the Hugo Modules for Hugo Blox. Attempt to resolve the issue by clearing Hugo’s module cache:

hugo mod clean
hugo server

If that does not resolve the issue, consider fetching a fresh copy of the latest Hugo Blox modules after clearing Hugo’s cache:

hugo mod clean
hugo mod get -u ./...
hugo server

Note: usually hugo mod clean should delete Hugo’s cache, however, users report a Hugo bug running the command in this situation. You can provide your feedback on the Hugo issues.

If Hugo’s hugo mod clean command fails to delete the Hugo cache (i.e. gives an error), see the workaround in the Error: failed to resolve output format section below.

If the above commands do not resolve the issue, then the Hugo Module for Hugo Blox may not have been fully setup if your site was setup prior to 2021. Check out config/_default/module.yaml (or config.yaml) alongside the go.mod file of one of the latest Hugo Blox templates on GitHub - you will need to copy the go.mod over to your site and copy the module.yaml over to your module.yaml.

Error: Go executable not found

Install Hugo’s Go dependency. If you believe that Go is already installed, perhaps Hugo was unable to detect Go due to installing either Go or Hugo in an isolated way such as via Linux Snaps. Users on all major platforms have reported success installing Hugo and Go by following the official Hugo Blox installation guide. You can also browse or report issues with Hugo detecting Go on the Hugo Forum.

Error: TOCSS failed to transform

There are two flavors of Hugo available to download. Hugo Blox and its templates require the full version of Hugo, named Hugo Extended. Learn how to install Hugo Extended.

Error: failed to unmarshal YAML

The error message provides you with the line number of a file which contains invalid YAML front matter. Either revert the change which broke the site or fix the YAML according to the details in the error message. You can learn about YAML syntax here.

To help prevent accidental YAML errors, consider using the Netlify CMS addon to edit content, rather than editing files directly.

Error: can’t evaluate field design in type *hugolib.pageState

This is a limitation of Hugo that the showcase view no longer works in Widget Pages (type: widget_page).

Either you can choose a different view, such as the card view, or you can convert the Widget Page to a Landing Page (the new version of the Widget Page) and use the Showcase view on a Landing Page (type: landing). Refer to the docs and _index.md in the latest Academic template for an examples of Landing Pages.

Error: Homepage not found

Seeing Homepage not found at /home/index.md?

If the page exists, then stop Hugo Server and then restart Hugo again.

Error: failed to download modules…unknown subcommand “mod”

Then click Deploys tab, and from the Trigger Deploy dropdown, choose Deploy Site.

Error: failed to download modules…not a git repository

Check your internet connection as per Bep’s comment. For reliable offline editing without relying on Hugo’s cache, consider vendoring your site with Hugo. (Also, manually deleting Hugo’s Module cache, from the location in the error message has been reported to resolve this error.)

If you are in China, GitHub may be blocked, and you need to either use a VPN or use the Chinese Go mirror in your config.

Errors converting an existing Hugo site to use Hugo Blox

Hugo Blox is a website framework rather than just a theme. Please follow the step-by-step guide on the Installation and Getting Started pages of the documentation.

If you experience issues, first try running Hugo on an unedited template and then compare the configuration parameters in the demo site’s config/ folder and front matter of content files with the files in your site.

Feel free to join the Hugo Blox community chat (link in the menu above) and post a detailed description of the issue with the error message and a link to your GitHub repository.

Publication filters not working

Hosting your site with Netlify or Cloudflare and experience strange behavior such as filters not working?

Disable post-processing steps such as minification in your Netlify/Cloudflare admin panel.

Content not in chronological order

A full, valid date, such as 2020-12-25, is required for each page and any other date fields. You can, however, customize how dates are displayed by editing the site configuration.

Random site generation behavior

Hugo is a multi-threaded application.

Sometimes there can be issues with concurrency and race conditions.

If you experience random behavior of things not rendering properly, try setting the environment variable HUGO_NUMWORKERMULTIPLIER=1. For example, run Hugo with HUGO_NUMWORKERMULTIPLIER=1 hugo server.