Troubleshooting & Common Issues

Fix common HugoBlox issues including deployment failures, Hugo errors, rendering problems, and configuration mistakes.

Community Support

Stuck? Join our Discord Community to chat live.

Deployment Issues

Changes Not Showing

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

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

Go to the Deploys tab in your Netlify dashboard.
Check the status of the latest deploy.
Click a failed deploy to view the build log.

Sometimes your browser caches the old version.

Force Refresh: Cmd+Shift+R (Mac) or Ctrl+F5 (Windows/Linux)
Incognito: Open the site in a private window.

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

Hugo Errors

`failed to resolve output format`

Cause: Hugo's module cache is corrupted.

Clear Cache (Recommended) Run this command to clear the module cache:
```
hugo mod clean --all
```
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"`

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

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

`Go executable not found`

HugoBlox requires Hugo Extended, which depends on Go.

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

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

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

Content Not in Chronological Order

Hugo requires a valid date format.

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

Random Rendering Behavior

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

HUGO_NUMWORKERMULTIPLIER=1 hugo server

`failed to download modules... not a git repository`

Check your internet connection.
If you are in China, configure a Go Proxy.