Quick fix: Hugo 0.146 'failed to parse' error

Table of Contents

Whilst rebuilding the theme behind this site I bumped Hugo past 0.146 and watched the build fall over with template parse errors. The fix is small if your theme is close to the standard layout, but the underlying changes are bigger than I first thought.

In this post I’ll cover the quick fix that unblocks most builds, and where to read the rest.

1.0 The symptom #

After upgrading Hugo, the build fails on one of your partials, shortcodes, or render hooks. The wording varies, but the gist is “failed to parse” or “template not found”, and the same theme worked fine on the previous Hugo version.

Info

TL;DR: Hugo 0.146 reorganised the layouts/ folder. Skip to the quick fix.

2.0 What changed #

Hugo 0.146 introduced a new template system. The two changes that catch most themes are:

The layouts/_default/ folder is gone. Everything inside it moves up to layouts/.
Special folders now sit at the top level with an underscore prefix: _partials, _shortcodes, _markup.

Hugo aims to keep older themes working through a legacy mapping layer, so plenty of sites upgrade silently. When the mapping does not catch your case, you get the parse error above.

3.0 Quick fix #

For the common case, three steps cover most themes:

cd themes/<your-theme>/layouts
git mv partials _partials
git mv shortcodes _shortcodes
git mv _default/* .
rmdir _default

The third command moves every file out of _default/ into the layouts root. That includes baseof.html, single.html, list.html, _markup/, and friends.

Then rebuild:

hugo --minify

Tip

Two specific gotchas worth knowing about:

layouts/index.html no longer renders the home page. Rename it to layouts/home.html.
taxonomy.html no longer covers term pages. Add a term.html if you have tags or categories.

If your build still fails, your theme is using a less common construct. The full migration table is on the official Hugo page (linked below).

4.0 Or pin Hugo whilst you migrate #

If you cannot move yet, pin Hugo to the last release before the change in your CI config. On AWS Amplify, that means downloading a specific extended build and putting it on PATH:

build:
  phases:
    preBuild:
      commands:
        - HUGO_VERSION=0.145.0
        - curl -sL "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" | tar -xz -C /tmp
        - mv /tmp/hugo /usr/local/bin/hugo

This buys time, but the migration itself takes a few minutes once you know what changed.

5.0 Further reading #

New template system in Hugo v0.146.0 — the official one pager with the full migration table.
Hugo v0.146.0 release announcement — the discourse thread with reported breakages.

6.0 Summary #

Hugo 0.146 reorganised layouts. The _default/ folder is gone, and special folders moved to underscore prefixed names at the root. Three renames fix most themes, and the official one pager covers the rest.

Thanks for reading!