golang/go · error

GOCACHE is not defined and %v

Error message

GOCACHE is not defined and %v

What it means

Returned by cache.DefaultDir() when GOCACHE is unset AND os.UserCacheDir() fails. With no default location available the cache is forced to "off" and the error records the underlying UserCacheDir failure. Subsequent build caching is disabled, so the user sees slow no-cache builds.

Source

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

	defaultDirChanged bool // effective value differs from $GOCACHE
	defaultDirErr     error
)

// DefaultDir returns the effective GOCACHE setting.
// It returns "off" if the cache is disabled,
// and reports whether the effective value differs from GOCACHE.
func DefaultDir() (string, bool, error) {
	// Save the result of the first call to DefaultDir for later use in
	// initDefaultCache. cmd/go/main.go explicitly sets GOCACHE so that
	// subprocesses will inherit it, but that means initDefaultCache can't
	// otherwise distinguish between an explicit "off" and a UserCacheDir error.

	defaultDirOnce.Do(func() {
		// 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
		}
	})

View on GitHub (pinned to b6b368adc5)

Solutions

1. Set HOME (or XDG_CACHE_HOME) so os.UserCacheDir() succeeds.
2. Set GOCACHE explicitly to an absolute directory the process can write.
3. If caching is intentionally off, set GOCACHE=off to silence the ambiguity.
4. For containers, add `ENV HOME=/tmp` or `ENV GOCACHE=/tmp/go-build`.

Example fix

# before: container with no HOME
$ go build .  # GOCACHE is not defined and $HOME is not defined

# after
$ export HOME=/tmp
$ go build .

if os.Getenv("GOCACHE") == "" {
    if _, err := os.UserCacheDir(); err != nil {
        // set a writable cache before invoking the toolchain
        _ = os.Setenv("GOCACHE", filepath.Join(os.TempDir(), "go-build"))
    }
}

When it happens

Trigger: GOCACHE env var unset and the platform cannot derive a user cache directory (HOME unset on Unix, or XDG_CACHE_HOME misconfigured; no home dir on a minimal container/service account).

Common situations: Docker/OCI images running as nobody without HOME; CI runners with stripped env; systemd services lacking Environment=HOME=; chroot/sandbox without passwd lookup.

Related errors

• not a directory
• GOCACHE is not an absolute path
• module cache not found: neither GOMODCACHE nor GOPATH is set
• GOMODCACHE entry is relative; must be absolute path: %q.\n
• GOENV=off

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