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

Error message

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

What it means

Returned by checkEnvWrite when GOMODCACHE is non-empty and not absolute. GOMODCACHE points at the downloaded-module cache and must be absolute so cache lookups are stable regardless of the go command's working directory.

Source

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

	// 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])
		}
	}

	if !utf8.ValidString(val) {

View on GitHub (pinned to b6b368adc5)

Solutions

Use an absolute path: `go env -w GOMODCACHE=$HOME/go/pkg/mod`.
Leave GOMODCACHE unset so it defaults to GOPATH[0]/pkg/mod.
For project-scoped caches, set GOMODCACHE in the OS env to an absolute per-project directory.

Example fix

# before
$ go env -w GOMODCACHE=./modcache
error: GOMODCACHE entry is relative; must be absolute path
# after
$ go env -w GOMODCACHE="$HOME/.cache/go-mod"

Defensive patterns

Strategy: validation

Validate before calling

func ensureAbs(v string) (string, error) {
    if v == "" || filepath.IsAbs(v) { return v, nil }
    return filepath.Abs(v)
}

Prevention

Leave GOMODCACHE unset when the default is acceptable.
Resolve cache paths to absolute before writing.
Use OS env for per-project caches with absolute directories.

When it happens

Trigger: `go env -w GOMODCACHE=./cache`, `go env -w GOMODCACHE=modcache`, or any non-empty relative value.

Common situations: Users trying to scope the module cache per-project; CI runners with relative cache directories; misconfigured GOPATH-relative defaults from custom setup scripts.

Related errors

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