golang/go · error

GOCACHE is not an absolute path

Error message

GOCACHE is not an absolute path

What it means

Returned by cache.DefaultDir() when GOCACHE is set to a non-empty value that is neither absolute nor the literal "off". A relative cache path is rejected because subprocesses and tool invocations resolve relative paths against differing working directories, which would scatter cache files unpredictably.

Source

Thrown at src/cmd/go/internal/cache/default.go:99

		// Compute default location.
		dir, err := os.UserCacheDir()
		if err != nil {
			defaultDir = "off"
			defaultDirErr = fmt.Errorf("GOCACHE is not defined and %v", err)
		} else {
			defaultDir = filepath.Join(dir, "go-build")
		}

		newDir := cfg.Getenv("GOCACHE")
		if newDir != "" {
			defaultDirErr = nil
			defaultDirChanged = newDir != defaultDir
			defaultDir = newDir
			if filepath.IsAbs(defaultDir) || defaultDir == "off" {
				return
			}
			defaultDir = "off"
			defaultDirErr = fmt.Errorf("GOCACHE is not an absolute path")
			return
		}
	})

	return defaultDir, defaultDirChanged, defaultDirErr
}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Use an absolute path: resolve with realpath/$(pwd) before exporting GOCACHE.
2. Or set GOCACHE=off to disable caching explicitly.
3. In scripts, write `export GOCACHE="$PWD/.go-cache"` instead of a relative value.

Example fix

# before
export GOCACHE=build-cache   # -> GOCACHE is not an absolute path

# after
export GOCACHE="$PWD/build-cache"

if v := os.Getenv("GOCACHE"); v != "" && v != "off" && !filepath.IsAbs(v) {
    abs, _ := filepath.Abs(v)
    _ = os.Setenv("GOCACHE", abs)
}

func isUsableGocache(v string) bool {
    return v == "off" || filepath.IsAbs(v)
}

When it happens

Trigger: GOCACHE=relative/path or GOCACHE=./go-build (anything not starting with / on Unix or a drive on Windows, and not "off").

Common situations: Makefiles/scripts exporting a relative GOCACHE; CI config with `GOCACHE: build-cache`; users trying to keep the cache inside the project tree with a relative path.

Related errors

• not a directory
• GOCACHE is not defined and %v
• GOMODCACHE entry is relative; must be absolute path: %q.\n
• module cache not found: neither GOMODCACHE nor GOPATH is set
• total length of command line and environment variables excee

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