[Common Issue] Why isn’t my Hugo theme working correctly with Netlify?

We get this question often. Luckily, there is both a common root cause for this issue and a solution for it!

Most often, Hugo themes added using git clone will not work with netlify. This is the common root cause I mentioned.

So, what is the solution, you ask? Use the git submodule command instead!

The Hugo team created fantastic (and detailed) documentation about this here also:

You can add a theme using some form of the git submodule command below below:

git submodule add git@github.com:example-user/example-theme.git themes/example-theme

Note: The command above is being run in the ‘base directory’ of the Hugo site. This is the directory that should contain Hugo specific sub-directories like content , public, static, and themes.

In many cases, this will resolve the theme not working issue. However, if the theme still isn’t working as expected, please let us know.

1 Like

I have switched my theme to be a submodule. I delete the theme and added it back using the syntax provided in this post but my theme is still not working. It’s like it is not there at all.

There are some details around using submodules that mean this may need additional configuration. Which site are you working on, please, so we can check the configuration and advise about any changes needed?

Thanks! The name in Netlify blograin which points to www.rainaldi.dev

Hi, @ljrain. This had me stumped because when I checked everything was properly “submoduled” for your repo. (And is “submoduled” a word?)

Also, I could only check because it was a public repo. Here in Netlify support, we cannot see your private repos - even if they are linked to your Netlify site.

Moving on, it turns out the issue is that the references to the CSS in the HTML are hard coded as being https://rainaldi.dev/css/paper.css not /css/paper.css. And because rainaldi.dev is not hosted by Netlify those HTTP requests fail with 404 errors and this in the browser console:

GET https://rainaldi.dev/css/paper.css net::ERR_NAME_NOT_RESOLVED

Because you can edit the HTML in Chrome, I tested this and changed those URLs to include the “www” like so: https://www.rainaldi.dev/css/paper.css.

With this added the CSS loaded the site shone in all its glory! :smiley:

So how do we fix this without manually editing the page in Chrome?

Well, one way is by editing config.toml (or config.yaml in your case) and changing the base URL like so:

baseURL: https://www.rainaldi.dev

Or, alternatively, you can point the “bare domain” of rainaldi.dev to Netlify and this will also resolve the issue (because the the CSS file will exist in both places now - but this isn’t required).

I believe there is a way to make Hugo create the CSS references as relative to the site and not include the domain name. But I haven’t figured out how to do this yet myself. (It should be possible - at least I hope it is - but I have had time to dig into the issue.) This is the third (but probably best) way to resolve this.

Finally, as a personal note I also use Hugo (and love it). If you find a way to make the CSS references relative, please feel free to @mention me here. I would really like to know too. :wink:

1 Like

Awesome!! Thank you so much! I have it fixed now. I changed the config just like you said.

I do not have the CSS hard coded, but I see exactly what you are talking about since the config had the root URL wrong. That would cause a problem… opps!

Thank you so much!


For public submodules the ssh format (git@github.com:) does not work and the correct syntax is the HTTPS format like so:

git submodule add https://github.com/example-user/example-theme.git themes/example-theme

Again, this only works for public submodules but also appears to always work for public submodules.

If it is a private submodule, then an SSH key needs to be created to access the private repo. We (Netlify Support) can create an SSH keypair for the Netlify site and then we’ll send you the public key portion to add to GitHub. (Note, there are additional steps required if there is more than one private submodule.)

If the HTTPS format doesn’t resolve the issue, please reply here and let us know about it! :+1:

1 Like

switching my project from ssh to https fixed the build snag, tyvm