Skip to content
HugoBlox Docs

Troubleshooting & Common Issues

Deployment Issues

Section titled “Deployment Issues”

Changes Not Showing

Section titled “Changes Not Showing”

If your updates aren’t appearing on the live site:

  1. Go to your repository’s Actions tab.
  2. Check for a yellow circle (in progress) or red cross (failed).
  3. Click a failed run to see the error log.

Common Cause: Invalid YAML. Paste your config into a YAML Validator to check for syntax errors.

Hugo Errors

Section titled “Hugo Errors”

failed to resolve output format

Section titled “failed to resolve output format”

Cause: Hugo’s module cache is corrupted.

  1. Clear Cache (Recommended) Run this command to clear the module cache:

    Terminal window
    hugo mod clean --all

  2. Manual Delete (If above fails) Delete the hugo_cache folder manually.

    • Mac/Linux: $TMPDIR/hugo_cache/
    • Windows: %TMP%\hugo_cache\

Cause: Missing Module Output

If you disabled a module (like Netlify) but left its outputs in hugo.yaml (e.g., headers, redirects), Hugo will fail. Remove the unused outputs from your configuration.

file "not found" or "failed to extract"

Section titled “file "not found" or "failed to extract"”

This usually means Hugo can’t download or find the required modules.

Terminal window
# Try clearing cache and updating modules
hugo mod clean
hugo mod get -u ./...
hugo server

Go executable not found

Section titled “Go executable not found”

HugoBlox requires Hugo Extended, which depends on Go.

  1. Ensure Go is installed.
  2. Ensure you are using Hugo Extended version.

TOCSS failed to transform

Section titled “TOCSS failed to transform”

You are likely using the standard version of Hugo. You must install Hugo Extended. View Installation Guide

failed to unmarshal YAML

Section titled “failed to unmarshal YAML”

You have a syntax error in a Front Matter or Config file. The error message usually provides a line number.

  • Check indentation (YAML is strict about spaces).
  • Ensure strings with special characters are quoted.

Runtime Issues

Section titled “Runtime Issues”

Content Not in Chronological Order

Section titled “Content Not in Chronological Order”

Hugo requires a valid date format.

  • Correct: date: 2023-12-25
  • Incorrect: date: 12/25/2023

Random Rendering Behavior

Section titled “Random Rendering Behavior”

Hugo is multi-threaded, which can sometimes cause race conditions on complex sites. Try running in single-worker mode:

Terminal window
HUGO_NUMWORKERMULTIPLIER=1 hugo server

failed to download modules... not a git repository

Section titled “failed to download modules... not a git repository”
  • Check your internet connection.
  • If you are in China, configure a Go Proxy.