major version suffixes must be in the form of /vN and are on

Error message

major version suffixes must be in the form of /vN and are only allowed for v2 or later:
	go mod init %s

What it means

During 'go mod init', the supplied module path failed SplitPathVersion and is NOT a gopkg.in path. The non-gopkg.in rule: major-version suffixes must be /vN and are only permitted for v2+. The message includes a suggestion from suggestModulePath (it strips a malformed suffix and proposes /v2 or /vN).

Source

Thrown at src/cmd/go/internal/modload/init.go:1272

		if pathErr, ok := err.(*module.InvalidPathError); ok {
			pathErr.Kind = "module"
			// Same as build.IsLocalPath()
			if pathErr.Path == "." || pathErr.Path == ".." ||
				strings.HasPrefix(pathErr.Path, "./") || strings.HasPrefix(pathErr.Path, "../") {
				pathErr.Err = errors.New("is a local import path")
			}
		}
		base.Fatal(err)
	}
	if err := CheckReservedModulePath(modPath); err != nil {
		base.Fatalf(`go: invalid module path %q: `, modPath)
	}
	if _, _, ok := module.SplitPathVersion(modPath); !ok {
		if strings.HasPrefix(modPath, "gopkg.in/") {
			invalidMajorVersionMsg := fmt.Errorf("module paths beginning with gopkg.in/ must always have a major version suffix in the form of .vN:\n\tgo mod init %s", suggestGopkgIn(modPath))
			base.Fatalf(`go: invalid module path "%v": %v`, modPath, invalidMajorVersionMsg)
		}
		invalidMajorVersionMsg := fmt.Errorf("major version suffixes must be in the form of /vN and are only allowed for v2 or later:\n\tgo mod init %s", suggestModulePath(modPath))
		base.Fatalf(`go: invalid module path "%v": %v`, modPath, invalidMajorVersionMsg)
	}
}

// fixVersion returns a modfile.VersionFixer implemented using the Query function.
//
// It resolves commit hashes and branch names to versions,
// canonicalizes versions that appeared in early vgo drafts,
// and does nothing for versions that already appear to be canonical.
//
// The VersionFixer sets 'fixed' if it ever returns a non-canonical version.
func fixVersion(ld *Loader, ctx context.Context, fixed *bool) modfile.VersionFixer {
	return func(path, vers string) (resolved string, err error) {
		defer func() {
			if err == nil && resolved != vers {
				*fixed = true
			}
		}()

View on GitHub (pinned to b6b368adc5)

Solutions

Follow the suggested command printed in the error (e.g. 'go mod init example.com/m/v2').
For v0/v1 modules, omit any suffix: 'go mod init example.com/m'.
Only add /vN (N>=2) when genuinely releasing a new major version, and keep N as a plain integer.
Avoid characters that break path parsing: spaces, commas, capital V.

Example fix

// before
$ go mod init example.com/m/version2
// major version suffixes must be in the form of /vN ...:
//   go mod init example.com/m/v2

// after
$ go mod init example.com/m/v2

Defensive patterns

Strategy: validation

Validate before calling

// Validate a non-gopkg.in module path before 'go mod init'.
func validModulePath(p string) error {
    if strings.HasPrefix(p, "gopkg.in/") { return nil }
    if _, _, ok := module.SplitPathVersion(p); !ok {
        return fmt.Errorf("path %s needs no suffix (v0/v1) or a /vN (N>=2) suffix", p)
    }
    return nil
}

Type guard

func isValidModulePathWithSuffix(p string) bool {
    _, _, ok := module.SplitPathVersion(p); return ok
}

Try / catch

out, err := exec.Command("go", "mod", "init", path).CombinedOutput()
if err != nil && bytes.Contains(out, []byte("major version suffixes must be in the form of /vN")) {
    suggested := extractSuggestedPath(out) // parse the embedded 'go mod init ...' hint
    out, err = exec.Command("go", "mod", "init", suggested).CombinedOutput()
}
return err

Prevention

For v0/v1 modules, omit any /vN suffix.
Only use /vN with N>=2, lowercase v, plain integer.
Validate the path with module.SplitPathVersion before init.
Let 'go mod init' suggest the form rather than guessing.

When it happens

Trigger: 'go mod init example.com/m/v2' but SplitPathVersion fails (e.g. malformed /v token like '/version2', or '/v0', '/v1' which are not allowed), or a path with no resolvable suffix on a v2+ intent.

Common situations: User adds /v2 but mistypes (/V2, /v-2); user puts /v1 thinking it is required; path has trailing slash or odd characters; first-time module authors.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/7f1018421e1c7a0e. Report an issue: GitHub.