modules: Improve error checking and messaging

[jwr0]

What version of Hugo are you using (hugo version)?

$ hugo version
0.151.0

Does this issue reproduce with the latest release?

Yes.

TLDR description

When using a config like this:

$ cat hugo.yml 
baseURL: 'https://example.org/'
languageCode: 'en-us'
title: 'My New Hugo Site'

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod
      version: v8.0

hugo serve will crash saying:

Error: command error: failed to load modules: failed to download module github.com/adityatelange/hugo-PaperMod@v8.0: failed to execute 'go [mod download -json github.com/adityatelange/hugo-PaperMod@v8.0]': failed to execute binary "go" with args [mod download -json github.com/adityatelange/hugo-PaperMod@v8.0]:  *errors.errorString

Steps to reproduce

1. mkdir example
2. docker run -it --rm -p 1313:1313 -v .:/project ghcr.io/gohugoio/hugo:v0.150.1 new site example
3. cd example
4. mv hugo.toml hugo.yml, then edit the file and change it into yaml, just because I prefer working with yaml.
5. docker run -it --rm -p 1313:1313 -v .:/project ghcr.io/gohugoio/hugo:v0.150.1 mod init example
6. Add an import to the config with a version key, so that the whole file looks like this:

baseURL: 'https://example.org/'
languageCode: 'en-us'
title: 'My New Hugo Site'

module:
  imports:
    - path: github.com/adityatelange/hugo-PaperMod
      version: v8.0

7. docker run -it --rm -p 1313:1313 -v .:/project ghcr.io/gohugoio/hugo:v0.150.1 serve --bind 0.0.0.0

I expect step 7 to download/install the module and serve the website, but instead I get this error:

Error: command error: failed to load modules: failed to download module github.com/adityatelange/hugo-PaperMod@v8.0: failed to execute 'go [mod download -json github.com/adityatelange/hugo-PaperMod@v8.0]': failed to execute binary "go" with args [mod download -json github.com/adityatelange/hugo-PaperMod@v8.0]:  *errors.errorString

8. Just to narrow down the scope of the problem, comment out the version key in the yaml config and run the serve command again, and it works as expected.

And just to confirm that the v8.0 tag of this module does exist, it's here: https://github.com/adityatelange/hugo-PaperMod/releases/tag/v8.0

A short note about the context of why I'm pinning this version

I build my site by way of GitHub Actions, so I can't rely on installing modules locally and expecting modules to remain at the same version on my local hard drive. If I build my site using v8.0 of a given module today in September 2025, I want to be able to walk away from the blog and come back to it 3 years later and push another commit and be sure that I'm still using the same dependencies/versions in 2028 as I used in 2025. I don't want a breaking change in my theme to break my site unless I have explicitly updated the version pin for the theme.

Links

Related issue: #13964
Related commit: 747cf4a (presumably)
Related author: @bep

Thanks for all your efforts on this great project.

[jmooring]

TLDR: Specify the commit hash:

[[module.imports]]
path = "github.com/adityatelange/hugo-PaperMod"
version = "a2eb47bb4b805116dcd34c1605d39835121f8dbe"

---

The github.com/adityatelange/hugo-PaperMod module does not use fully qualified semantic versioning as described here:
https://go.dev/ref/mod#version-queries

all queries consider available versions reported by go list -m -versions

$ go list -m -versions github.com/adityatelange/hugo-PaperMod
github.com/adityatelange/hugo-PaperMod

By way of comparison:

$ go list -m -versions github.com/google/docsy
github.com/google/docsy v0.1.0 v0.2.0-pre v0.2.0 v0.3.0 v0.4.0 v0.5.0 v0.5.1 v0.6.0 v0.7.0 v0.7.1 v0.7.2 v0.8.0 v0.9.0 v0.9.1 v0.10.0 v0.11.0 v0.12.0

$ go list -m -versions github.com/CaiJimmy/hugo-theme-stack/v3
github.com/CaiJimmy/hugo-theme-stack/v3 v3.0.0 v3.1.0 v3.2.0 v3.3.0 v3.4.0 v3.5.0 v3.6.0 v3.7.0 v3.8.0 v3.9.0-alpha v3.9.0 v3.9.1 v3.9.2 v3.10.0 v3.11.0 v3.12.0 v3.13.0 v3.14.0 v3.15.0 v3.16.0 v3.17.0 v3.18.0 v3.19.0 v3.20.0 v3.21.0 v3.22.0 v3.23.0 v3.24.0 v3.24.1 v3.24.2 v3.25.0 v3.26.0 v3.27.0 v3.28.0 v3.29.0 v3.30.0 v3.31.0

The current error message:

Error: failed to load modules: failed to download module github.com/adityatelange/hugo-PaperMod@v8.0: failed to execute 'go [mod download -json github.com/adityatelange/hugo-PaperMod@v8.0]': failed to execute binary "go" with args [mod download -json github.com/adityatelange/hugo-PaperMod@v8.0]: *errors.errorString

If possible, it would be nice if that included a little more detail.

[jwr0]

@jmooring thanks for your quick reply. I was able to get this working using a commit hash as you described.

I guess maybe this issue should now be a request for a documentation clarification, instead of for a code bug fix. A person like me who is a computer nerd in general but not a golang developer probably wouldn't know the difference between generic git tags versus golang semantic versions, which is where my confusion came from. If the documentation was able to call out that difference, and especially if it was able to help a person understand whether or not their desired open source module uses the required versioning, that would be awesome.

I'm happy to answer questions if any further context is needed. Otherwise, I'll leave it up to the hugo maintainers if this ticket should be used for any docs updates or if it should just be closed. I personally have no further questions now that @jmooring pointed out the thing that was confusing me. Thanks again @jmooring.

[jmooring]

We have a brief documentation reference to version queries here:
https://gohugo.io/configuration/module/#version

This will get more detail with the implementation of gohugoio/hugoDocs#3200.

See related issue adityatelange/hugo-PaperMod#1796.

---

Changing this from a bug to an enhancement. We need to capture the error message from the JSON string sent to stdout.

The -json flag causes download to print a sequence of JSON objects
to standard output, describing each downloaded module (or failure),
corresponding to this Go struct:

    type Module struct {
        Path     string // module path
        Query    string // version query corresponding to this version
        Version  string // module version
        Error    string // error loading module
        Info     string // absolute path to cached .info file
        GoMod    string // absolute path to cached .mod file
        Zip      string // absolute path to cached .zip file
        Dir      string // absolute path to cached source root directory
        Sum      string // checksum for path, version (as in go.sum)
        GoModSum string // checksum for go.mod (as in go.sum)
        Origin   any    // provenance of module
        Reuse    bool   // reuse of old module info is safe
    }