golang/go · warning

GOENV=off

Error message

GOENV=off

What it means

Returned by cfg.EnvFile() when GOENV is explicitly set to "off". This is a legitimate, intentional setting that disables loading/writing the persistent go-env file (~/.../go/env); EnvFile surfaces it as an error so callers can distinguish "disabled" from "default path". It is informational rather than a fault.

Source

Thrown at src/cmd/go/internal/cfg/cfg.go:352

var OrigEnv []string

// CmdEnv is the new environment for running go tool commands.
// User binaries (during go test or go run) are run with OrigEnv,
// not CmdEnv.
var CmdEnv []EnvVar

var envCache struct {
	once   sync.Once
	m      map[string]string
	goroot map[string]string
}

// EnvFile returns the name of the Go environment configuration file,
// and reports whether the effective value differs from the default.
func EnvFile() (string, bool, error) {
	if file := os.Getenv("GOENV"); file != "" {
		if file == "off" {
			return "", false, fmt.Errorf("GOENV=off")
		}
		return file, true, nil
	}
	dir, err := os.UserConfigDir()
	if err != nil {
		return "", false, err
	}
	if dir == "" {
		return "", false, fmt.Errorf("missing user-config dir")
	}
	return filepath.Join(dir, "go/env"), false, nil
}

func initEnvCache() {
	envCache.m = make(map[string]string)
	envCache.goroot = make(map[string]string)
	if file, _, _ := EnvFile(); file != "" {
		readEnvFile(file, "user")

View on GitHub (pinned to b6b368adc5)

Solutions

1. Treat the returned error as expected when GOENV=off is intended; do not propagate it as fatal.
2. If env-file behavior is needed, unset GOENV (or set it to a path) instead of off.
3. Callers should check for this specific error string/value before failing.

Example fix

// before: any EnvFile error is fatal
f, changed, err := cfg.EnvFile()
if err != nil { return err }

// after: tolerate the documented GOENV=off case
f, changed, err := cfg.EnvFile()
if err != nil && err.Error() != "GOENV=off" { return err }

func isGoenvOff(err error) bool {
    return err != nil && err.Error() == "GOENV=off"
}

f, changed, err := cfg.EnvFile()
if err != nil {
    if err.Error() == "GOENV=off" {
        // env file intentionally disabled; proceed without it
        return
    }
    return err
}

When it happens

Trigger: GOENV=off is exported and a code path calls cfg.EnvFile() expecting a usable file path. The error signals that no env file should be read or written.

Common situations: Reproducible/locked-down CI that pins all config via real env vars; sandboxed builds that forbid writes outside the workdir; users following hardening guides.

Related errors

• missing user-config dir
• GOCACHE is not defined and %v
• module cache not found: neither GOMODCACHE nor GOPATH is set
• GOMODCACHE entry is relative; must be absolute path: %q.\n
• globalThis.crypto is not available, polyfill required (crypt

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