Fixing Hugo Theme Compatibility Issues in Cloudflare Pages
It was a quiet bank holiday afternoon when I decided to update the theme for this blog. I’ve always appreciated the elegance of simple yet effective CI/CD pipelines, especially for static websites. For that reason, I leverage a workflow that ties Github to Cloudflare Pages. Little did I know that this routine update would lead me down a rabbit hole of version compatibility issues - a reminder that even the simplest systems can sometimes surprise us.
The Perfect Deployment Workflow Gone Wrong
My favorite deployment workflow for Hugo-based static websites is deceptively simple:
Push to GitHub → Cloudflare Pages automatically builds and deploys.
This approach embodies CI/CD principles applied to web hosting, providing a seamless experience where Git commits trigger Cloudflare to rebuild the website and deploy it to production (or a test subdomain, depending on your branch configuration).
While I generally prefer self-hosted, on-prem, more sovereign infrastructure, in IT it’s important to use systems where their strengths lie and this is a typical case of what the cloud does best.
This workflow removes much of the hosting burden for simple sites. It offers automatic deployment, source control integration, and minimizes vulnerability concerns - a perfect balance of convenience and control.
Recently, I updated the theme for this blog, and to my surprise, the build failed on Cloudflare Pages despite working perfectly on my local machine.
The classic “it worked on my machine” problem! 😂
Cloudflare provides full build logs:
2025-05-01T04:08:19.208398Z WARN Module "anatole" is not compatible with this Hugo version; run "hugo mod graph" for more information.
2025-05-01T04:08:19.208968Z Start building sites …
2025-05-01T04:08:19.209156Z hugo v0.118.2-da7983ac4b94d97d776d7c2405040de97e95c03d+extended linux/amd64 BuildDate=2023-08-31T11:23:51Z VendorInfo=gohugoio
2025-05-01T04:08:19.209239Z
2025-05-01T04:08:19.347101Z ERROR render of "page" failed: "/opt/buildhome/repo/themes/anatole/layouts/_default/baseof.html:12:6": execute of template failed: template: _default/single.html:12:6: executing "_default/single.html" at <partial "head.html" .>: error calling partial: "/opt/buildhome/repo/themes/anatole/layouts/partials/head.html:52:82": execute of template failed: template: partials/head.html:52:82: executing "partials/head.html" at <css>: can't evaluate field Sass in type interface {}
And after examining the logs, I realized the issue: the Hugo version running by default on Cloudflare Pages (v0.118.2) was too old to work with the latest update of my theme.
The Simple Fix
Fortunately, the solution was straightforward. First, I needed to check which Hugo version I was running locally:
guillaume@laptop3:~ $ hugo version
hugo v0.142.0+extended linux/amd64 BuildDate=2025-01-24T00:00:00+00:00 VendorInfo=Fedora:0.142.0-4.fc42
Next, I went to Cloudflare Workers settings and forced the same specific version by defining a variable under “Variables and Secrets”.
I added a new variable:
- Name:
HUGO_VERSION - Value:
extended_0.142.0
After saving this change, I returned to the “Deployments” tab and clicked “Retry deployment”.
This time, the build succeeded:
2025-05-01T04:20:45.04829Z Installing hugo extended_0.142.0
2025-05-01T04:20:45.171329Z Downloading hugo release extended_0.142.0...
2025-05-01T04:20:46.61574Z hugo extended_0.142.0 installation was successful!
2025-05-01T04:20:46.88028Z Executing user command: hugo
2025-05-01T04:20:47.108505Z Start building sites...
2025-05-01T04:20:47.108971Z hugo v0.142.0-1f746a872442e66b6afd47c8c04ac42dc92cdb6f+extended linux/amd64 BuildDate=2025-01-22T12:20:52Z VendorInfo=gohugoio
...
2025-05-01T04:21:02.834825Z Success: Your site was deployed!
Why This Matters
This seemingly small issue highlights an important aspect of modern web development: version compatibility across different environments. What works locally might fail in production if you’re not careful about matching versions.
The Cloudflare Pages and Hugo combination is powerful, but it’s important to remember that Hugo themes are often version-dependant. When your theme gets updated, it might require a newer Hugo version than what’s provided by default in your build environment.
By explicitly setting the Hugo version in your deployment configuration, you ensure consistency between your development and production environments, preventing unexpected surprises during deployment.