Upgrading hugo version broke website

I’m trying to update an old website built in 2021 - unfortunately I don’t have records of which hugo version it was made with originally, but my guess is it’s whathever was current around the time. So far it all seems very broken. To give an example it took me 2 hours just to dig up that I needed to replace “.Site.IsServer” by “hugo.IsServer”.

So my first question would be is there any documentation of breaking changes I could have a look at to get an idea what kinds of things have changed?

And I also have a specific question regarding the error I’m currently on. It looks like my .Site.Params is not populated the same as it used to. Specifically all params from particular files seem to be missing:
hugo/
├─ config/
│ ├─ default/
│ │ ├─ config.yaml
│ │ ├─ languages.de.yaml
│ │ ├─ languages.en.yaml
│ │ ├─ params.footer.de.yaml
│ │ ├─ params.footer.en.yaml
│ │ ├─ params.hero.de.yaml
│ │ ├─ params.hero.en.yaml

Params from the “params” section in config.yaml are included in .Site.Params, while those from
params.footer.en.yaml, params.hero.en.yaml are not there (in neither language). I’ve been reading a lot in the documentation and right now I can’t even find any mention of a file structure like the one I have, so I’m thinking maybe that is the problem? It used to work though.

I know the question is a bit vague and its probably not possible to pinpoint my exact problems without more details. So any general pointers for what I should be looking into would be much appreciated :slight_smile:

Changes are documented in the release notes here Releases · gohugoio/hugo · GitHub. There will be quite a few releases to read through since 2021.

Nothing stops you from downloading an old version, e.g. Release v0.89.4 · gohugoio/hugo · GitHub, and use that to build your site.

If you only need to update some content that would likely be my first option.

If you on the other hand plan to actively develop the site it’s likely woth the effort to update your theme. Hugo has added a lot of features and improvements over the years.

1 Like

Regarding configuration directory see configuration-directory docs.

1 Like

Thanks a lot! :slight_smile: I managed to fix a bunch of errors including the config/params issues I mentioned before and the site now builds again. However when opening http://localhost:1313/ or any other url like http://localhost:1313/imprint/ it only shows “Page not found”.

For reference here is the output of hugo server

hugo server --logLevel debug --environment local --printI18nWarnings --disableFastRender --gc --cleanDestinationDir --openBrowser  --navigateToChanged

WARN  DEPRECATED: Kind "taxonomyterm" used in disableKinds is deprecated, use "taxonomy" instead.
WARN  deprecated: site config key privacy.twitter.disable was deprecated in Hugo v0.141.0 and will be removed in a future release. Use privacy.x.disable instead.
Watching for changes in C:\Users\...Website\hugo\{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in C:\Users\...\Website\hugo\config\_default, C:\Users\...\Website\hugo\config\local
Start building sites …
hugo v0.146.5-61328976e11cbb9d906b4a790b8a7cd25b2a914f+extended windows/amd64 BuildDate=2025-04-15T17:54:38Z VendorInfo=gohugoio

INFO  static: removing all files from destination that don't exist in static dirs
INFO  static: syncing static files to \ duration 217.918ms
INFO  build:  step process substep collect files 61 files_total 61 pages_total 61 resources_total 0 duration 2.5044ms
INFO  build:  step process duration 3.5096ms
INFO  build:  step assemble duration 0s
WARN  found no layout file for "html" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN  calling IsSet with unsupported type "string" (string) will always return false.
WARN  Linking page C:/Users/.../Website/hugo/content/services/development.en.md via params.url /#development
WARN  i18n|MISSING_TRANSLATION|en|notFound
WARN  i18n|MISSING_TRANSLATION|en|home
WARN  i18n|MISSING_TRANSLATION|en|archives
INFO  build:  step render substep pages site en outputFormat html duration 1.8684026s
INFO  build:  step render substep pages site en outputFormat rss duration 2.5047ms
INFO  build:  step render pages 18 content 41 duration 1.8719079s
INFO  build:  step render deferred count 0 duration 0s
INFO  build:  step postProcess duration 0s
INFO  build:  duration 1.8754175s

                   | EN
-------------------+------
  Pages            |  18
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 211
  Processed images |  37
  Aliases          |   0
  Cleaned          |   0

Built in 2099 ms
Environment: "local"
Serving pages from disk
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) en
Press Ctrl+C to stop

I also checked the hugo/public directory and it does seem to build the files there correctly, I have an index.html and if I open it it has the correct content.
Also the sitemap.xml has all urls as I would expect them:

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>http://localhost:1313/%23development/</loc>
</url>
<url>
<loc>http://localhost:1313/</loc>
</url>
<url>
<loc>http://localhost:1313/imprint/</loc>
</url>
<url>
<loc>http://localhost:1313/team/</loc>
</url>
<url>
<loc>http://localhost:1313/privacy/</loc>
</url>
</urlset>

However all of the above show page not found. I’ve been googling the issue for a while and mostly this seems to be either theme or language/localization related. I looked into both and so far I couldn’t really find an issue with either on my page. Is there any way (other than loglevel which I already used) how I can get hugo server to output more information that might help me with debugging this? Is there any way to inspect what urls are pointing to which local directory or similar? Any tips are much appreciated :slight_smile:

In the output avobe there are a number of warnings, i,e, “WARN”. Start by fixing them one by one.

If you need more help we will need a link to your repo.

The warnings didn’t sound like they would be related to localhost:1313 displaying “Page not found”, especially since I can see the html files are built correctly - but sure I will try to get those fixed :slight_smile:

Unfortunately this is a work thing and I’m generally not allowed to share any code publicly. I understand that makes it difficult to help. That’s why I was trying to ask for pointers how I could go about debugging it and where/how I can get more information on how my local files like hugo/public/index.html are linked to the urls like localhost:1313?

could be a config error. check

basurl, uglyurls, permalinks…

maybo you can post your config?

and there are heavy changes in the templat lookup system with 0.146.0-5

maybe give 0.145.0 a try

update lines corrected
tgese two warnings may affect i think

1 Like

Thanks for the help! :slight_smile: I fixed the warnings you mentioned, but unfortunately still getting the “Page not found”. I also tried v0.145.0 but it didn’t seem to change the issue so I switched back.

I’ll post a somewhat censored config

hugo.yaml

defaultContentLanguage: en
disableLanguages:
  - de
enableInlineShortcodes: true
timeout: 120s
markup:
  defaultMarkdownHandler: "goldmark"
  goldmark:
    renderer:
      unsafe: true
imaging:
  resampleFilter: "Lanczos" # "box"
theme: 
  - hugo-fresh
  - timeline
disableKinds:
- taxonomy
privacy:
  disqus:
    disable: true
  googleAnalytics:
    disable: true
  instagram:
    disable: true
  x:
    disable: true
  vimeo:
    disable: true
  youtube:
    disable: true
    privacyEnhanced: true
params:
  navbar:
    dropdown: false
    logo:
      image: images/logos/logo.png
      hoverimage: images/logos/logo_hover.png
      link: /
      alt: logo alt
  openGraph: true
  debug: false
  sidebar: false
  font:
    name: "Open Sans"
    sizes: [400,600]
  defaults:
    hero:
      buttonlink: "#"
      image: illustrations/hero.png

languages.en.yaml

baseURL: http://www.companydomain.com/
languageName: English
weight: 1
languageCode: en
title: Company | Foo & Bar

menus.en.yaml

navbar:
  - identifier: services
    name: Services
    url: /
    weight: 1
  - identifier: about
    name: Team
    url: team/#team
    weight: 2
  - identifier: projects
    name: Projects
    url: team/#projects
    weight: 3
  - identifier: foo_bar
    name: Foo's bar
    url: "#anchor"
    weight: 5
    params:
      button: true
  - identifier: jobs
    name: Jobs
    url: /
    weight: 4
    params:
      only_render_if_has_children: true

params.en.yaml

description: Lorem ipsum dolor.
images:
  - "/images/image.png"

foo:
  title: foo
  subtitle: foo bar baz
  logos:
  - logo1.png
  - logo2.png
foo_bar:
  title: Foo Bar!
  subtitle: Foo bar <a href="mailto:foo@domain.com">foo@domain.com</a>
  form:
    action: /foo.php
    class: form foo
    button_a: Foo A
    button_b: Foo B
    textA: Lorem Ipsum Dolor :)
    textB: 'Lorem ipsum <a href="mailto:foo@domain.com">foo@domain.com</a>'
    things:
      - name: name
        label: label
        description: lorem ipsum
      - name: nameB
        label: labelB
        description: lorem ipsum
footer:
  logo: logo.png
  fooflag: false

Additionally there is also languages.de.yaml, menus.de.yaml, params.de.yaml but they all follow the exact same structure as their english counterpart and are unused.

according to: Configure menus you should use pageRef instead of url in menu

what about contentInSubdir? where are your english pages.

check your html file
where does it point to
is a page there in public

if not
which template generates the bad ref
use templates.Current to assist

if - oops multilang. maybe en is port 1414

without source it’s digging in the dark

just got a tip covering the fragments part of your menu entries. have a look at that one

So it turned out the page not found issue was somehow a language thing, once I added defaultContentLanguageInSubdir: true to my hugo.yaml it started showing my page under http://localhost:57636/. While I don’t really understand why I would HAVE to do this in order for it to work, I am okay with using this setting. However a bunch of links, including also pictures and stylesheets are broken, because they used to be inside the public/en/ (and public/de/) subfolder, but now they are directly in public instead.

As an example, my partial for including stylesheets uses the following code:

{{- $inServerMode := hugo.IsServer }}
{{- $sass         := "style.sass" }}
{{- $cssTarget    := "css/style.css" }}
{{- $cssOpts      := cond ($inServerMode) (dict "targetPath" $cssTarget "enableSourceMap" true) (dict "targetPath" $cssTarget "outputStyle" "compressed") }}
{{- $css := resources.Get $sass | toCSS $cssOpts }}
<link rel="stylesheet" type="text/css" href="{{ $css.RelPermalink }}">

which in the html looks like

<link rel="stylesheet" type="text/css" href="/css/style.css">

however http://localhost:57636/ points to the public/en/ subdirectory and the stylesheet lies in public/css/style.css, so not inside the public/en/ subdirectory where it used to be previously. Therefore the <link> is not working. I have the same issue with images and other resources and I’m not sure what would be the proper way to fix it?

You don’t have to - just digging in the dark

The embedded image render hook is automatically enabled for multilingual single-host sites if duplication of shared page resources is disabled. This is the default configuration for multilingual single-host sites.

more details:Default Image Render Hook and Multilingual

you specified a target path: targetPath" $cssTarget :wink:

no way for me to dig in with just some code fragments, sry

1 Like

So it turns out the way I linked my stylesheets, images etc. is actually working fine if I remove the following lines from my hugo.yaml

disableLanguages:
  - de

With both languages enabled, it now duplicates the images, css and other folders into the /en/ and /de/ subdirectories as expected. Is it possible that hugo has issues with using multilingual mode but second language disabled, so effectively only one language is there? It seems to me there might be a bug, that causes the duplication in the language subdirectories to not happen in this case?

Anyhow, I have everything working perfectly now when both languages are enabled. The question is how can I get it to work with de disabled again (since the translation has not been finished yet and should only go live once everything is there)?