golang/go · error

unknown go command variable %s

Error message

unknown go command variable %s

What it means

Returned by checkEnvWrite when the key passed to `go env -w` is not a recognised go command variable (cfg.CanGetenv(key) is false and the key is not already present in the env file). It catches typos and arbitrary names before they are written to the env config.

Source

Thrown at src/cmd/go/internal/envcmd/env.go:653

		"GOGCCFLAGS",
		"GOHOSTARCH",
		"GOHOSTOS",
		"GOMOD",
		"GOROOT",
		"GOTELEMETRY",
		"GOTELEMETRYDIR",
		"GOTOOLDIR",
		"GOVERSION",
		"GOWORK":
		return fmt.Errorf("%s cannot be modified", key)
	case "GOENV", "GODEBUG":
		return fmt.Errorf("%s can only be set using the OS environment", key)
	}

	// To catch typos and the like, check that we know the variable.
	// If it's already in the env file, we assume it's known.
	if !cfg.CanGetenv(key) {
		return fmt.Errorf("unknown go command variable %s", key)
	}

	// Some variables can only have one of a few valid values. If set to an
	// invalid value, the next cmd/go invocation might fail immediately,
	// even 'go env -w' itself.
	switch key {
	case "GO111MODULE":
		switch val {
		case "", "auto", "on", "off":
		default:
			return fmt.Errorf("invalid %s value %q", key, val)
		}
	case "GOPATH":
		if strings.HasPrefix(val, "~") {
			return fmt.Errorf("GOPATH entry cannot start with shell metacharacter '~': %q", val)
		}
		if !filepath.IsAbs(val) && val != "" {
			return fmt.Errorf("GOPATH entry is relative; must be absolute path: %q", val)

View on GitHub (pinned to b6b368adc5)

Solutions

1. Check the spelling against `go help environment` and `go env -json` output.
2. Run `go env` to list currently-known keys and match your key exactly (case-sensitive).
3. If the variable is from a newer Go release, upgrade the toolchain (GOTOOLCHAIN=auto or install a newer Go).
4. Confirm the variable is a go-command variable at all — shell-only vars (e.g. SHELL, PATH) do not belong in `go env -w`.

Example fix

# before
$ go env -w GOPRXY=https://proxy.golang.org
error: unknown go command variable GOPRXY
# after — correct spelling
$ go env -w GOPROXY=https://proxy.golang.org,direct

// Build the set of known go variables from `go env -json`, then validate.
func isValidGoVar(key string, known []string) bool {
    for k := range known { if k == key { return true } }
    return false
}
if !isValidGoVar(key, knownVars) {
    return fmt.Errorf("refusing `go env -w %s`: unknown variable", key)
}

When it happens

Trigger: `go env -w TYPO=1`, `go env -w MYVAR=foo`, or any key not in cfg.CanGetenv's known set and not already in the user's go env file.

Common situations: Typos like GOPRXY instead of GOPROXY; copying a shell var name into `go env -w`; using a var name from a newer/older Go version not supported by this toolchain.

Related errors

• %s cannot be modified
• %s can only be set using the OS environment
• invalid %s value %q
• GOPATH entry cannot start with shell metacharacter '~': %q
• GOPATH entry is relative; must be absolute path: %q

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