Debug Hugo build errors

Hugo's error messages are technically accurate and almost always pinpoint the exact file and line of the problem. But they're written for the Hugo runtime, not for you. Hugo Chat translates them into a working fix.

The basic flow

1. Run hugo or hugo server and copy the full error block.
2. Paste it into Hugo Chat.
3. Read the explanation, apply the fix, rebuild.

That's the loop. The rest of this page covers what to include and how to debug stubborn cases.

What to include in your prompt

The headline of a Hugo error is rarely enough. Always paste:

• The full error block, including the file path and line number.
• The Hugo version (hugo version).
• If you have a repo connected, mention it (@you/your-blog).

@you/your-blog hugo build is failing — fix this:

ERROR render of "taxonomy" failed: "/themes/ananke/layouts/_default/taxonomy.html:5:7":
execute of template failed: template: _default/taxonomy.html:5:7: executing
"_default/taxonomy.html" at <.Site.Taxonomies>: range can't iterate over <nil>

Hugo Chat will tell you which file to edit and what to change.

Common error families

partial not found

Means a partial template is being called from a path Hugo can't resolve. Usually fixed by either creating the missing partial in layouts/partials/ or correcting the call site.

Note: Hugo recently moved layouts/partials/ to layouts/_partials/ in newer versions. If your theme is on the old path and your Hugo is new (or vice versa), this is the likely cause.

range can't iterate over <nil>

A range is being passed something that doesn't exist. Often a taxonomy that hasn't been declared in hugo.toml, or a content collection that's empty.

executing "..." at <.Param "X">: error calling Param

A template expects a frontmatter or config param that isn't set. Hugo Chat will tell you which param and where to set it.

failed to extract shortcode

A shortcode call has a syntax error or references a shortcode that doesn't exist. Usually a typo or a missing file in layouts/shortcodes/.

When the error is opaque

Some Hugo errors point at generated files or deeply nested templates. When the error doesn't help:

1. Ask Hugo Chat with the error and the page that triggered it (e.g. "I get this error when I visit /posts/my-post/").
2. If you have a repo connected, Hugo Chat can read the involved files directly and trace the problem.

When the build succeeds but the output is wrong

Build errors are easy. "It built but the page is empty" is harder. For these:

@you/your-blog the /tags/ page is rendering but it's empty.
There are 50+ tagged posts in content/. What's wrong with my taxonomy
config?

Hugo Chat will check hugo.toml, your taxonomy templates, and your content frontmatter to find the disconnect.