GOPATH entry is relative; must be absolute path: %q

Error message

GOPATH entry is relative; must be absolute path: %q

What it means

Returned by checkEnvWrite when a GOPATH entry is non-empty and not absolute (filepath.IsAbs returns false). Relative GOPATH entries would resolve against the go command's working directory, producing unstable module/binary locations, so they are rejected at write time.

Source

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

		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)
		}
		if !filepath.IsAbs(args[0]) && args[0] != filepath.Base(args[0]) {
			return fmt.Errorf("%s entry is relative; must be absolute path: %q", key, args[0])

View on GitHub (pinned to b6b368adc5)

Solutions

Resolve to an absolute path before writing: `go env -w GOPATH=$(pwd)/.gopath`.
Use $HOME-relative absolute paths such as `go env -w GOPATH=$HOME/go`.
On multi-entry GOPATH, make sure every entry is absolute.

Example fix

# before
$ go env -w GOPATH=./gopath
error: GOPATH entry is relative; must be absolute path
# after
$ go env -w GOPATH="$PWD/gopath"

Defensive patterns

Strategy: validation

Validate before calling

import "path/filepath"

func ensureAbsGopath(v string) (string, error) {
    if v == "" || filepath.IsAbs(v) { return v, nil }
    abs, err := filepath.Abs(v)
    if err != nil { return "", err }
    return abs, nil
}

Prevention

Resolve paths to absolute before `go env -w`.
For multi-entry GOPATH, normalise every entry independently.
Prefer $HOME-relative absolute paths in shared configs.

When it happens

Trigger: `go env -w GOPATH=./go`, `go env -w GOPATH=go`, or any non-empty relative entry inside a colon-separated GOPATH.

Common situations: Project-local GOPATH attempts; CI scripts that cd before invoking `go env -w` with a relative path; users copying tutorial examples that omit the leading slash.

Related errors

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