Troubleshooting

Some common questions and answers are listed below.

Table of Contents

Changes do not show on my site

If there is a progress indicator, Netlify is still 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.

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

Feel free to join the Wowchemy 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.

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 config.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/wowchemy/wowchemy-hugo-themes/modules/wowchemy-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 Wowchemy. 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 Wowchemy 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 Wowchemy may not have been fully setup if your site was setup prior to 2021. Learn how to add the Hugo Module to your site.

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 Wowchemy 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. Wowchemy 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: Homepage not found

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

Possible causes:

A Widget Page was modified whilst running Hugo Server
- Stop Hugo Server and then restart it
content/home/index.md is missing
- Add the /home/index.md homepage file to each language’s content folder
- For example, your site should have a content/home/ folder containing index.md and your homepage sections, or for multi-language sites, content/en/home/ and content/zh/home/ etc.
- Refer to the ‘Build Your Homepage’ and ‘Language’ documentation pages as well as the example homepage file

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.)

Errors converting an existing Hugo site to use Wowchemy

Wowchemy 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 Wowchemy 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.