GOPATH entry cannot start with shell metacharacter '~': %q

Error message

GOPATH entry cannot start with shell metacharacter '~': %q

What it means

Returned by checkEnvWrite when a GOPATH entry starts with '~'. The tilde is a shell metacharacter that the go command does not expand, so storing it would silently create a literal '~' directory. Rejected to prevent confusing path-resolution bugs later.

Source

Thrown at src/cmd/go/internal/envcmd/env.go:668

	// To catch typos and the like, check that we know the variable.
	// If it's already in the env file, we assume it's known.
	if !cfg.CanGetenv(key) {
		return fmt.Errorf("unknown go command variable %s", key)
	}

	// Some variables can only have one of a few valid values. If set to an
	// invalid value, the next cmd/go invocation might fail immediately,
	// even 'go env -w' itself.
	switch key {
	case "GO111MODULE":
		switch val {
		case "", "auto", "on", "off":
		default:
			return fmt.Errorf("invalid %s value %q", key, val)
		}
	case "GOPATH":
		if strings.HasPrefix(val, "~") {
			return fmt.Errorf("GOPATH entry cannot start with shell metacharacter '~': %q", val)
		}
		if !filepath.IsAbs(val) && val != "" {
			return fmt.Errorf("GOPATH entry is relative; must be absolute path: %q", val)
		}
	case "GOMODCACHE":
		if !filepath.IsAbs(val) && val != "" {
			return fmt.Errorf("GOMODCACHE entry is relative; must be absolute path: %q", val)
		}
	case "CC", "CXX":
		if val == "" {
			break
		}
		args, err := quoted.Split(val)
		if err != nil {
			return fmt.Errorf("invalid %s: %v", key, err)
		}
		if len(args) == 0 {
			return fmt.Errorf("%s entry cannot contain only space", key)

View on GitHub (pinned to b6b368adc5)

Solutions

Expand the tilde yourself to an absolute path: `go env -w GOPATH=$HOME/go` after substituting $HOME, or use the resolved absolute path directly.
On multi-entry GOPATH, ensure none of the colon-separated entries begins with '~'.
Keep GOPATH configuration in your shell rc file (where tilde expansion happens) rather than in `go env -w`.

Example fix

# before
$ go env -w GOPATH=~/go
error: GOPATH entry cannot start with shell metacharacter '~'
# after — expand the absolute path first
$ go env -w GOPATH="$HOME/go"

Defensive patterns

Strategy: validation

Validate before calling

import "strings"

func sanitizeGopathEntry(v string) (string, error) {
    if strings.HasPrefix(v, "~") {
        return "", fmt.Errorf("GOPATH must not start with '~': %q", v)
    }
    return v, nil
}

Prevention

Always expand '~' to $HOME before persisting paths.
Keep tilde-dependent lines in shell rc files where the shell expands them.
Lint for tilde-prefixed paths in config generators.

When it happens

Trigger: `go env -w GOPATH=~/go`, or any GOPATH entry whose first character is '~' (including in colon-separated multi-entry GOPATH on POSIX).

Common situations: Users coming from bash configs that lean on tilde expansion; copy-pasting `export GOPATH=~/go` style lines into `go env -w`; cross-platform shell setups that assume tilde expansion.

Related errors

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