module cache not found: neither GOMODCACHE nor GOPATH is set

Error message

module cache not found: neither GOMODCACHE nor GOPATH is set

What it means

Thrown by `checkCacheDir` when `cfg.GOMODCACHE` is empty. The comment notes that modload.Init normally sets GOMODCACHE from GOPATH[0]/pkg/mod, so this error indicates a severely misconfigured environment where neither GOMODCACHE nor GOPATH is set. Without a cache directory, the module system cannot download, store, or verify modules.

Source

Thrown at src/cmd/go/internal/modfetch/cache.go:820

	}

	return nil
}

var (
	statCacheOnce sync.Once
	statCacheErr  error

	counterErrorsGOMODCACHEEntryRelative = counter.New("go/errors:gomodcache-entry-relative")
)

// checkCacheDir checks if the directory specified by GOMODCACHE exists. An
// error is returned if it does not.
func checkCacheDir(ctx context.Context) error {
	if cfg.GOMODCACHE == "" {
		// modload.Init exits if GOPATH[0] is empty, and cfg.GOMODCACHE
		// is set to GOPATH[0]/pkg/mod if GOMODCACHE is empty, so this should never happen.
		return fmt.Errorf("module cache not found: neither GOMODCACHE nor GOPATH is set")
	}
	if !filepath.IsAbs(cfg.GOMODCACHE) {
		counterErrorsGOMODCACHEEntryRelative.Inc()
		return fmt.Errorf("GOMODCACHE entry is relative; must be absolute path: %q.\n", cfg.GOMODCACHE)
	}

	// os.Stat is slow on Windows, so we only call it once to prevent unnecessary
	// I/O every time this function is called.
	statCacheOnce.Do(func() {
		fi, err := os.Stat(cfg.GOMODCACHE)
		if err != nil {
			if !os.IsNotExist(err) {
				statCacheErr = fmt.Errorf("could not create module cache: %w", err)
				return
			}
			if err := os.MkdirAll(cfg.GOMODCACHE, 0o777); err != nil {
				statCacheErr = fmt.Errorf("could not create module cache: %w", err)
				return

View on GitHub (pinned to b6b368adc5)

Solutions

Set GOPATH: `export GOPATH=$HOME/go` (GOMODCACHE derives from it)
Set GOMODCACHE directly: `export GOMODCACHE=$HOME/go/pkg/mod`
Run `go env -w GOPATH=$HOME/go` to persist the setting
Ensure `go env GOROOT` is valid; a broken install can produce empty env values

Example fix

# before: neither set
go mod download  # fails
# after
export GOPATH=$HOME/go
go mod download

Defensive patterns

Strategy: validation

Validate before calling

// Ensure module cache environment is configured
import (
    "os"
    "path/filepath"
)

func ensureModCacheConfigured() error {
    gomodcache := os.Getenv("GOMODCACHE")
    if gomodcache == "" {
        gopath := os.Getenv("GOPATH")
        if gopath == "" {
            home, _ := os.UserHomeDir()
            gopath = filepath.Join(home, "go")
        }
        gomodcache = filepath.Join(gopath, "pkg", "mod")
        os.Setenv("GOMODCACHE", gomodcache)
    }
    if !filepath.IsAbs(gomodcache) {
        return fmt.Errorf("GOMODCACHE must be absolute: %q", gomodcache)
    }
    return nil
}

Prevention

Set GOPATH or GOMODCACHE in shell profile (.bashrc, .zshrc) for persistence
Use `go env -w GOPATH=...` for permanent configuration
In CI/Docker, explicitly set GOPATH in the environment

When it happens

Trigger: Any go command that touches the module cache when cfg.GOMODCACHE is empty string. This happens when GOPATH is unset/empty (modload.Init would normally set GOMODCACHE from it) and GOMODCACHE is explicitly empty. The check `if cfg.GOMODCACHE == ""` triggers.

Common situations: GOPATH and GOMODCACHE both unset in a minimal environment (e.g., fresh container, CI without Go env setup); GOPATH set to empty string explicitly; broken go installation where `go env` returns empty values; environment variable stripped in sandboxed builds.

Related errors

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