golang/go · error

invalid %s version: %q

Error message

invalid %s version: %q

What it means

Thrown by parsePathVersionOptional when the path portion differs from the raw argument (meaning a `@version` suffix was supplied) but the version token needs quoting per modfile.MustQuote (e.g. contains spaces, special characters, or otherwise would not round-trip as a single token). The version is reported verbatim.

Source

Thrown at src/cmd/go/internal/workcmd/edit.go:301

// parsePathVersionOptional parses path[@version], using adj to
// describe any errors.
func parsePathVersionOptional(adj, arg string, allowDirPath bool) (path, version string, err error) {
	before, after, found, err := modload.ParsePathVersion(arg)
	if err != nil {
		return "", "", err
	}
	if !found {
		path = arg
	} else {
		path, version = strings.TrimSpace(before), strings.TrimSpace(after)
	}
	if err := module.CheckImportPath(path); err != nil {
		if !allowDirPath || !modfile.IsDirectoryPath(path) {
			return path, version, fmt.Errorf("invalid %s path: %v", adj, err)
		}
	}
	if path != arg && !allowedVersionArg(version) {
		return path, version, fmt.Errorf("invalid %s version: %q", adj, version)
	}
	return path, version, nil
}

// flagEditworkReplace implements the -replace flag.
func flagEditworkReplace(arg string) {
	before, after, found := strings.Cut(arg, "=")
	if !found {
		base.Fatalf("go: -replace=%s: need old[@v]=new[@w] (missing =)", arg)
	}
	old, new := strings.TrimSpace(before), strings.TrimSpace(after)
	if strings.HasPrefix(new, ">") {
		base.Fatalf("go: -replace=%s: separator between old and new is =, not =>", arg)
	}
	oldPath, oldVersion, err := parsePathVersionOptional("old", old, false)
	if err != nil {
		base.Fatalf("go: -replace=%s: %v", arg, err)
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Quote the version properly in the shell and ensure it contains no spaces or special chars: `@v1.2.3`.
2. Use a canonical semver tag or a clean shortened commit hash.
3. Remove the `@version` suffix if you want the latest version resolved later.
4. Check modfile.MustQuote rules: avoid spaces, `"`, `@`, and control characters.

Example fix

# before
// go work edit -replace foo@"v1.2.3 beta"

# after
// go work edit -replace foo@v1.2.3

// Ensure the version token does not require quoting
if path != arg && modfile.MustQuote(version) {
    log.Fatalf("version %q contains characters that require quoting; clean it", version)
}

When it happens

Trigger: Run `go work edit -replace foo@bad version=bar@v1` or any work-edit argument whose `@version` portion contains characters modfile.MustQuote flags — whitespace, quotes, `@`, control chars, or a token that is not a clean version identifier.

Common situations: Pasting a version with a trailing comment or space (`@v1.2.3 `); using a commit hash containing unusual characters; mixing shell quoting so a space lands inside the version; targeting a version string with an embedded `@`.

Related errors

• invalid %s path: %v
• %v is not a regular file
• non-file URL
• file URL missing path
• file URL encodes volume in host field: too few slashes?

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