golang/go · error

missing user-config dir

Error message

missing user-config dir

What it means

Returned by cfg.EnvFile() when GOENV is unset, os.UserConfigDir() succeeds, but returns an empty string — there is no usable user-config directory to host the go/env file. Distinct from a UserConfigDir error (which is propagated verbatim): here the platform API gave a meaningless empty result.

Source

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

	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")
	}
	goroot := findGOROOT(envCache.m["GOROOT"])
	if goroot != "" {
		readEnvFile(filepath.Join(goroot, "go.env"), "GOROOT")
	}

	// Save the goroot for func init calling SetGOROOT,
	// and also overwrite anything that might have been in go.env.
	// It makes no sense for GOROOT/go.env to specify

View on GitHub (pinned to b6b368adc5)

Solutions

1. Set GOENV explicitly to a writable file path.
2. Set HOME / XDG_CONFIG_HOME so UserConfigDir returns a real directory.
3. Set GOENV=off if the env file is not needed at all.

Example fix

# before
$ go env   # missing user-config dir

# after
$ export GOENV=$HOME/.config/go/env
$ go env

if os.Getenv("GOENV") == "" {
    if d, _ := os.UserConfigDir(); d == "" {
        _ = os.Setenv("GOENV", filepath.Join(os.TempDir(), "go-env"))
    }
}

When it happens

Trigger: GOENV unset; os.UserConfigDir() returns ("", nil) — possible on minimal/embedded platforms or when the config-dir resolver finds nothing but does not error.

Common situations: Stripped-down containers, embedded targets, or custom builds where the config directory resolver yields empty; misconfigured HOME/XDG_CONFIG_HOME that resolves to an empty value.

Related errors

• GOENV=off
• 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/293d24a97d5baf4d. Report an issue: GitHub.