Troubleshooting
Symptoms, their usual causes, and the fix.
Building
hugo: command not found, or “requires Hugo 0.158.0 or newer”. Hugo isn’t installed, or an old one is. See
Install the tools, then open a new terminal and check hugo version.
“module … not found” or “go: command not found”. The theme is a Hugo module, which needs Go. Install Go, or add the theme as a Git submodule instead (Create your site).
The site has no styles at all. Hugo didn’t find the theme. Check the [module] block (or theme = "fieldnotes"
with a submodule) and that hugo mod get ran.
A setting has no effect. Most often TOML: a line after [params.something] belongs to that table. Move plain
[params] lines above all [params.…] tables.
A change doesn’t show while hugo server runs. Stop it with Ctrl+C and start it again; after changing
hugo.toml, a data file or a new template, the running server sometimes misses it.
Writing
Maths shows as plain text with backslashes. The passthrough setting is missing from hugo.toml, or the page
lacks math: true (Maths and code).
Code has no colours. noClasses = false under [markup.highlight] is missing.
A photo’s title isn’t shown as a caption. wrapStandAloneImageWithinParagraph = false under
[markup.goldmark.parser] is missing, or the photo shares its paragraph with text.
A post doesn’t appear. It’s a draft (draft: true), its date is in the future, or its section isn’t in
mainSections. hugo server -D shows drafts.
HTML in a post is missing. Hugo leaves raw HTML in Markdown out on purpose; write a shortcode instead.
Trips
“gallery: … can’t be processed (heic)”. HEIC photos can’t be processed; export them as JPEG.
Warnings about photos without alt text. Write an alt for each in photos.yaml
(Photo galleries).
The map shows “The map needs a MapTiler key”. HUGO_MAPTILER_KEY wasn’t set when Hugo built the site: run
source .env before hugo server, or add the MAPTILER_KEY secret on GitHub (The MapTiler
key).
The map stays grey or blank online. Your site’s address isn’t among the key’s allowed origins in MapTiler, or the month’s free map loads are used up. Your browser’s developer console (right-click → Inspect → Console) names the cause.
Publishing
The published site has no styles, or links lead to the wrong place. baseURL doesn’t match the address. With
the workflow, the address comes from GitHub; check that Pages’ source
is “GitHub Actions”.
The workflow fails at “hugo”. Its log under Actions shows Hugo’s error, the same you’d see locally: run
hugo on your computer to reproduce it.