Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/go: improve error message for mismatched major versions #41512

Open
glycerine opened this issue Sep 20, 2020 · 11 comments
Open

cmd/go: improve error message for mismatched major versions #41512

glycerine opened this issue Sep 20, 2020 · 11 comments
Labels
modules NeedsFix okay-after-beta1
Milestone

Comments

@glycerine
Copy link

@glycerine glycerine commented Sep 20, 2020

related to
#35732
which remains the top google hit for this error

what does one do to get this simple example to work?

jaten@jatens-MacBook-Pro ~/etcd-embed $ go build
go: errors parsing go.mod:
/Users/jaten/etcd-embed/go.mod:3: require go.etcd.io/etcd: version "v3.4.13" invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v3
jaten@jatens-MacBook-Pro ~/etcd-embed $ go version
go version go1.14.4 darwin/amd64
jaten@jatens-MacBook-Pro ~/etcd-embed $ cat go.mod
module github.com/glycerine/etcd-embed

require go.etcd.io/etcd v3.4.13
                                      
go 1.14

          
jaten@jatens-MacBook-Pro ~/etcd-embed $ cat main.go
package main

import (
	"log"
	"time"

	"go.etcd.io/etcd/v3/embed"
)

func main() {
	cfg := embed.NewConfig()
	cfg.Dir = "default.etcd"
	e, err := embed.StartEtcd(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer e.Close()
	select {
	case <-e.Server.ReadyNotify():
		log.Printf("Server is ready!")
	case <-time.After(60 * time.Second):
		e.Server.Stop() // trigger a shutdown
		log.Printf("Server took too long to start!")
	}
	log.Fatal(<-e.Err())
}
jaten@jatens-MacBook-Pro ~/etcd-embed $

if I change go.mod to

module github.com/glycerine/etcd-embed

require go.etcd.io/etcd/v3 v3.4.13

go 1.14

I get the equally mystifying

jaten@jatens-MacBook-Pro ~/etcd-embed $ go build
go: go.etcd.io/etcd/v3@v3.4.13: go.mod has non-.../v3 module path "go.etcd.io/etcd" (and .../v3/go.mod does not exist) at revision v3.4.13
jaten@jatens-MacBook-Pro ~/etcd-embed $
@andig
Copy link
Contributor

@andig andig commented Sep 21, 2020

Imho v3 denotes a v3 major module version. Seems your module in question is v1 (although it has a 3.xyz version number), so omit the /v3 suffix when requiring it. While this sounds confusing it is imho due to keeping backwards compatibility with modules what introduced versioning before go.mod came around in go 1.11.

@andig
Copy link
Contributor

@andig andig commented Sep 21, 2020

Imho you need to change the module path to the github-hosted one which declares itself as v3.

@bcmills bcmills changed the title unacceptably poor UX for go.mod: invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v3 cmd/go: improve error message for mismatched major versions Sep 21, 2020
@bcmills
Copy link
Member

@bcmills bcmills commented Sep 21, 2020

As noted in #35732 (comment):

[W]e do want to make the errors as clear as possible. If you have a specific improvement to suggest in the phrasing of the error, please open a new issue (or send a change with the proposed improvement)!

That said, I've been thinking about this particular error message some more. I think the error message we've written today assumes that the module path is correct and the version is wrong (because it doesn't match the module path), when really most users who encounter this error really have written the version they intend: we should suggest a fix to the path, not to the version.

CC @jayconrod @matloob

@bcmills
Copy link
Member

@bcmills bcmills commented Sep 21, 2020

@glycerine, in this case, the problem is that the latest v3-tagged release of go.etcd.io/etcd (v3.4.13) has declared the wrong module path for that major version (it should instead be go.etcd.io/etcd/v3). That issue has been fixed at head (etcd-io/etcd@96cce20), but not yet included in a tagged release. (That is etcd-io/etcd#12068 / etcd-io/etcd#12109.)

The go command intentionally does not try untagged commits when a release tag exists for the requested major version, but you could fetch such a commit explicitly using go get -d go.etcd.io/etcd/v3@master.

@bcmills bcmills added modules NeedsFix labels Sep 22, 2020
@bcmills bcmills added this to the Go1.16 milestone Sep 22, 2020
@Skarlso
Copy link
Contributor

@Skarlso Skarlso commented Dec 9, 2020

@bcmills This has tripped me off several times already, so if we could make this more clear I would be delighted to create a CL with a clearer message.

@dzrtc
Copy link

@dzrtc dzrtc commented Jan 29, 2021

That said, I've been thinking about this particular error message some more. I think the error message we've written today assumes that the module path is correct and the version is wrong (because it doesn't match the module path), when really most users who encounter this error really have written the version they intend: we should suggest a fix to the path, not to the version.

@bcmills I can appreciate that this situation puts the tooling into a dark room with little content to draw from to understand what's going on or how to inform the user. Go error messages are typically terse, but perhaps verbosity is called for here. Consider whether it would actually be easier to describe the error state if there wasn't an implicit assumption that error messages need be short.

For example, include several examples, include a link to that paper you've previously linked to regarding module versions, include corrections for real-world variations of this problem, etc. A good technical writer might be helpful here.

@bcmills
Copy link
Member

@bcmills bcmills commented Jan 29, 2021

A good technical writer might be helpful here.

That would be @stevetraut. 🙂

@icholy
Copy link

@icholy icholy commented Jan 29, 2021

Maybe something like this?

require go.etcd.io/etcd: version "v3.4.13" invalid: module contains a go.mod file, so path must contain major version: should be go.etcd.io/etcd/v3

@dzrtc
Copy link

@dzrtc dzrtc commented Jan 29, 2021

@icholy This advice is better but would not address the situation that happened to me (see "Getting the Major Version Fails" at comment #35732 (comment)).

@icholy
Copy link

@icholy icholy commented Jan 29, 2021

@dzrtc

$ go get -u github.com/golang-migrate/migrate@v4
go get github.com/golang-migrate/migrate@v4: no matching versions for query "v4"

I checked http://github.com/golang-migrate/migrate and it doesn't have a branch or tag called v4. What do you find confusing about this error?

@jayconrod jayconrod added the okay-after-beta1 label May 17, 2021
@jayconrod jayconrod removed this from the Go1.17 milestone Jul 29, 2021
@jayconrod jayconrod added this to the Backlog milestone Jul 29, 2021
@gopherbot
Copy link

@gopherbot gopherbot commented Jan 21, 2022

Change https://golang.org/cl/378400 mentions this issue: cmd/go/internal/modfetch: do not short-circuit canonical versions

gopherbot pushed a commit that referenced this issue Feb 3, 2022
Since at least CL 121857, the conversion logic in
(*modfetch).codeRepo.Stat has had a short-circuit to use the version
requested by the caller if it successfully resolves and is already
canonical.

However, we should not use that version if it refers to a branch
instead of a tag, because branches (unlike tags) usually do not refer
to a single, stable release: a branch named "v1.0.0" may be for the
development of the v1.0.0 release, or for the development of patches
based on v1.0.0, but only one commit (perhaps at the end of that
branch — but possibly not even written yet!) can be that specific
version.

We already have some logic to prefer tags that are semver-equivalent
to the version requested by the caller. That more general case
suffices for exact equality too — so we can eliminate the
special-case, fixing the bug and (happily!) also somewhat simplifying
the code.

Fixes #35671
Updates #41512

Change-Id: I2fd290190b8a99a580deec7e26d15659b58a50b0
Reviewed-on: https://go-review.googlesource.com/c/go/+/378400
Trust: Bryan Mills <bcmills@google.com>
Run-TryBot: Bryan Mills <bcmills@google.com>
Reviewed-by: Russ Cox <rsc@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
modules NeedsFix okay-after-beta1
Projects
None yet
Development

No branches or pull requests

8 participants