Troubleshooting

Some common questions and answers are listed below.

Table of Contents

Changes do not show on my site

Login to Netlify and check the status of the latest deploy in the Deploys tab.

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: 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

If Hugo’s hugo mod clean command fails to delete Hugo cache, the hugo_cache folder can be removed manually nowby deleting $TMPDIR/hugo_cache/ (see Hugo Docs for details).

If the above commands do not resolve the issue, then the Hugo Module for Wowchemy may not have been fully setup. 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”

Login to Netlify and set GO_VERSION to 1.12 in your Environment settings.

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.

Error: failed to resolve output format

Temporarily remove the "WebAppManifest", "redirects", "headers" output types from your config.yaml and run:

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

Check that hugo now runs OK with hugo server and then add back in the output types.

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.

Previous