What causes "invalid buildmode: %q" in golang/go?

Check the valid buildmode values: go help buildmode

invalid buildmode: %q

Error message

invalid buildmode: %q

What it means

The Go linker's BuildMode.Set method rejects an unrecognized -buildmode flag value. Valid build modes are: exe (standalone executable), pie (position-independent executable), c-archive (C-compatible static archive), c-shared (C-compatible shared library), shared (shared library for Go programs), and plugin (Go plugin). Any other string triggers this error.

Source

Thrown at src/cmd/link/internal/ld/config.go:34

// in cmd/go, and are documented in 'go help buildmode'.
type BuildMode uint8

const (
	BuildModeUnset BuildMode = iota
	BuildModeExe
	BuildModePIE
	BuildModeCArchive
	BuildModeCShared
	BuildModeShared
	BuildModePlugin
)

// Set implements flag.Value to set the build mode based on the argument
// to the -buildmode flag.
func (mode *BuildMode) Set(s string) error {
	switch s {
	default:
		return fmt.Errorf("invalid buildmode: %q", s)
	case "exe":
		switch buildcfg.GOOS + "/" + buildcfg.GOARCH {
		case "darwin/arm64", "windows/arm64": // On these platforms, everything is PIE
			*mode = BuildModePIE
		default:
			*mode = BuildModeExe
		}
	case "pie":
		*mode = BuildModePIE
	case "c-archive":
		*mode = BuildModeCArchive
	case "c-shared":
		*mode = BuildModeCShared
	case "shared":
		*mode = BuildModeShared
	case "plugin":
		*mode = BuildModePlugin
	}

View on GitHub (pinned to b6b368adc5)

Solutions

Check the valid buildmode values: go help buildmode
Correct the spelling to one of: exe, pie, c-archive, c-shared, shared, plugin
Verify shell quoting is correct: -buildmode=c-shared not -buildmode c -shared
If using a build script, ensure the buildmode variable is set correctly

Example fix

# before
go build -buildmode=library main.go

# after
go build -buildmode=c-archive main.go

Defensive patterns

Strategy: validation

Validate before calling

// Validate buildmode before passing to linker
var validBuildModes = map[string]bool{
    "exe": true, "pie": true, "c-archive": true,
    "c-shared": true, "shared": true, "plugin": true,
}

func validateBuildMode(s string) error {
    if !validBuildModes[s] {
        return fmt.Errorf("invalid buildmode %q; valid: exe, pie, c-archive, c-shared, shared, plugin", s)
    }
    return nil
}

Try / catch

// Handle buildmode errors in build scripts
if err := mode.Set(buildmodeFlag); err != nil {
    fmt.Fprintf(os.Stderr, "Error: %v\nRun 'go help buildmode' for valid options.\n", err)
    os.Exit(1)
}

Prevention

Check valid values with: go help buildmode
Validate buildmode in build scripts before invoking go build
Use shell completion or validation in CI to catch typos

When it happens

Trigger: The flag.Value Set method is called by the Go flag parser with the user-supplied -buildmode argument. If the string does not match any of the six known cases, the default branch returns this formatted error including the offending value.

Common situations: Typo in the buildmode name (e.g. 'c-share' instead of 'c-shared'); using a deprecated buildmode name; passing a value intended for a different flag; shell quoting issues that concatenate the flag and value incorrectly.

Related errors

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