Running on Hugo?

Hugo build broken after a theme upgrade? We bring it back.

Hugo is beautifully fast until the day a theme bump breaks every template path, or the shortcodes rendered in an old version stop rendering in the new one. We take on the sites that cannot build any more, rewire the partials against the current API, and leave behind layouts that will survive the next upgrade.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

hugo-build.log

still failing

What it is

Hugo at a glance

Hugo is an open-source static site generator written in Go, started by Steve Francia in 2013 and now maintained by Bjorn Erik Pedersen and a wide group of contributors. It compiles Markdown and data into static HTML with a Go template language, and is best known for how fast it builds: thousands of pages in seconds on a laptop.

The project supports content organized into sections, taxonomies, multilingual sites, and output formats such as HTML, RSS and JSON generated from the same content. Themes are distributed as Git submodules or Hugo Modules. Modern versions have moved toward lowercase template functions (site, hugo, lang) and away from the old capitalized .Site, .Hugo, .Language forms, which is where a lot of upgrade pain comes from.

Type
Static site generator
First released
2013
License
Apache 2.0
Maintained by
The Hugo project and Bjorn Erik Pedersen
Typically used for
Documentation sites, developer blogs, marketing microsites, multilingual content sites

The honest version

Hugo pros and cons

No technology is all upside. This is where Hugo earns its place and where it tends to cause trouble.

Where Hugo is strong

  • Build speed is genuinely remarkableA site with a thousand pages compiles in a second or two on commodity hardware, which keeps the authoring loop pleasant and the CI minute count low.
  • A single binary with no runtimeYou download hugo and you run it. There is no Node version, no Python virtualenv and no Ruby bundler to keep aligned across a team.
  • Content modeling is thoroughSections, taxonomies, data files, front matter, and resources sit together in a predictable tree. Large content projects stay navigable even after years of growth.
  • First-class multilingual supportMultiple languages are a feature of the build, not a plugin bolted on top. Translations live beside the source document with their own front matter.
  • Assets pipeline built inSCSS, PostCSS and image processing are handled by Hugo Pipes without needing webpack or esbuild in the mix, which is one less moving part.

Where Hugo bites

  • The template language is a steep learning curveGo templates read nothing like Liquid, Jinja or Nunjucks. Range, with, dict and the dot context trip up people who come from any other SSG, and the errors are not always clear.
  • Upgrades across many versions stingDeprecations between 0.80 and current have been real, and a site that was last built on 0.74 does not come forward to 0.123 without template rewrites and theme updates.
  • Themes rot when they are not maintainedA theme downloaded as a submodule years ago may reference functions, shortcodes or output formats that no longer exist, and the only path is to fork and fix.
  • No built-in authoring UIWriters edit Markdown and front matter in a text editor. Non-technical authors need a layer such as Forestry, TinaCMS, or Netlify CMS, all of which are themselves maintenance.
  • Error messages are bluntA nil pointer in a template points at the line but not at why the data is missing, and tracking it down usually means printing the whole context with printf.

Sound familiar?

Common Hugo problems we fix

The Hugo problems that bring people to us, and what you have once each one is fixed.

partial not found: partials/header.html

Theme upgrade broke every template path

A newer version of the theme moved partials into a subdirectory, or the submodule got updated without the layouts in the site project being rewired. The build fails on the first page.

Partials resolving against the current theme

found no layout file for page

Pages render with the wrong template

Hugo's layout lookup is a chain of fallbacks, and a change to type, kind or section pushes pages onto a layout that was never meant for them, often the index.

Lookup chain producing the right template

.Site.GetPage is deprecated

The site builds but every page is full of deprecation warnings

A codebase written against the capitalized API from the 0.60 era still runs, but logs are noisy, and the next major version is likely to remove the old names entirely.

Templates on the current API

nil pointer evaluating interface {}.foo

A template crashes on pages where a field is missing

Code that calls .Params.foo directly on pages where foo was never set. The with guard was skipped, and the build dies on the one article that did not have the field.

Templates safe against missing data

REF_NOT_FOUND: Ref "/old/url.md"

Internal links are broken after a restructure

Content moved between sections, and the ref and relref shortcodes still point at the old paths. The build either warns or errors depending on configuration.

Internal links tracked and resolved

downgrade not supported by cache

The site is pinned to a Hugo version from years ago

A build that only works on 0.89, with a theme and templates that will not survive upgrading, and CI images on their way out of support.

Upgraded on a rehearsed path

Shortcode .figure is undefined

A custom shortcode disappeared on upgrade

An old theme shortcode that was overridden locally, and the override got lost during a submodule reset. Articles that used it now break in rendering.

Shortcodes restored and tested

Pages: 2,418 Total time: 18741 ms

Build times have climbed into the tens of seconds

Image processing on every build, a resource loop that re-walks the tree, or a shortcode doing expensive work on pages that never change.

Build times back where they should be

What we do

Hugo help, from rescue to upkeep

Call us for one broken build, or hand us the whole repo.

Rescue
A site that will not build on a current Hugo, a theme that no longer renders, or a deploy pipeline that stopped after a version bump. We bring the build back first.
Upgrades
Moving a legacy Hugo site through the deprecations onto a current version, updating templates to the lowercase API, and keeping the theme working across the move.
Themes and layouts
A theme written or forked to match a specific brand, with the shortcodes, partials and output formats the editors actually use, documented so the next upgrade is uneventful.
Authoring workflows
A headless CMS in front of the Markdown, previews on PRs, and image handling that does not make editors copy files by hand.
Multilingual and performance
Multiple languages set up against Hugo's native support, with image processing tuned so large sites keep building fast.
Managed Tech
Dependency watch, periodic Hugo upgrades, build monitoring, and someone on call when the CI pipeline stops producing a site.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Hugo alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Hugo questions

Something else? Call+1 737 727 7327

Why does our Hugo site refuse to build after a version bump?

The most common cause is a theme pinned to an old API: template functions that were lowercased, output formats that moved, or shortcodes removed. Second most common is a change in layout lookup that quietly pushes content onto the wrong template. We walk the build with a pinned and a current Hugo in parallel until the diff is visible, and fix the templates rather than downgrading.

Can you upgrade a Hugo site that is five years out of date?

Yes, and this is a common piece of work. We take the current content, rebuild against a modern Hugo in a branch, port the templates onto the lowercase API, replace the theme with a maintained one or fork the existing one, and only then plan the cutover. The content itself almost never has to change.

Should we move from Hugo to a headless CMS like Sanity or Storyblok?

It depends on who is editing. If the writers are developers or technical editors comfortable in Markdown, Hugo plus Netlify or Cloudflare Pages is hard to beat on cost and speed. If marketing wants an inline editor, images uploaded from a phone, or scheduled publishing, a headless CMS in front of Hugo or a different platform entirely is probably the right call.

Why is our Hugo build slow now?

The usual culprits are images being processed on every run because the cache was lost in CI, a shortcode doing expensive work on every page, or a huge taxonomy producing pages that are rebuilt whether or not they changed. We profile the build and fix the specific step, not the whole pipeline.

How do we handle preview deploys and non-technical editors on Hugo?

We usually put TinaCMS or a lightweight headless like Decap in front of the repo, wire PR previews on Netlify or Cloudflare Pages, and build an editing interface that produces clean Markdown. Editors stop touching Git, and the site keeps the Hugo build and hosting model.

How much does Hugo help cost?

Quotes do not cost anything. Describe the repo, the version it is on, and the error messages you are seeing, and you get a price before any work begins.

Free estimate

Hugo giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.