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

Error message

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

What it means

Thrown by `checkCacheDir` when GOMODCACHE is set but `filepath.IsAbs` returns false — the path is relative rather than absolute. The module cache must be an absolute path because relative paths would resolve differently depending on the working directory, causing cache misses and inconsistent behavior. Note the format string ends with `\n` (a literal newline in the error message, which is unusual and likely a minor formatting quirk).

Source

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

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
			}
			return
		}
		if !fi.IsDir() {

View on GitHub (pinned to b6b368adc5)

Solutions

Set GOMODCACHE to an absolute path: `export GOMODCACHE=$HOME/go/pkg/mod`
Use `$(pwd)` to absolutize a relative path: `export GOMODCACHE=$(pwd)/go-cache`
Run `go env -w GOMODCACHE=/absolute/path/to/cache` to persist
Check that GOPATH (from which GOMODCACHE may derive) is absolute

Example fix

# before: relative path
export GOMODCACHE=./pkg/mod
# after: absolute path
export GOMODCACHE=$HOME/go/pkg/mod

Defensive patterns

Strategy: validation

Validate before calling

import (
    "os"
    "path/filepath"
)

func ensureGomodcacheAbsolute() error {
    c := os.Getenv("GOMODCACHE")
    if c != "" && !filepath.IsAbs(c) {
        abs, _ := filepath.Abs(c)
        os.Setenv("GOMODCACHE", abs)
    }
    return nil
}

Prevention

Always use absolute paths for GOMODCACHE and GOPATH
Use $HOME or $(pwd) prefix to construct absolute paths in scripts
Validate environment in CI setup scripts before running go commands

When it happens

Trigger: Setting GOMODCACHE to a relative path like `./pkg/mod`, `../cache`, or `go-cache`. The `filepath.IsAbs(cfg.GOMODCACHE)` check returns false. A counter `counterErrorsGOMODCACHEEntryRelative` is incremented for telemetry before the error is returned.

Common situations: Setting GOMODCACHE in a script or Makefile with a relative path; GOPATH set relatively (if GOMODCACHE derives from it); misconfigured CI with relative cache paths; `.env` files using relative paths for portability that backfire here.

Related errors

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