What causes "buildmode %s not supported on %s/%s" in golang/go?

Check the Go documentation for buildmode platform support matrix

buildmode %s not supported on %s/%s

Error message

buildmode %s not supported on %s/%s

What it means

The Go linker validates that the requested buildmode is supported on the target GOOS/GOARCH platform combination using platform.BuildModeSupported. Even if the buildmode string is recognized, some combinations are unsupported (e.g. shared mode requires Linux, plugin mode has limited platform support, c-shared requires specific architectures).

Source

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

		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
	}

	if !platform.BuildModeSupported("gc", s, buildcfg.GOOS, buildcfg.GOARCH) {
		return fmt.Errorf("buildmode %s not supported on %s/%s", s, buildcfg.GOOS, buildcfg.GOARCH)
	}

	return nil
}

func (mode BuildMode) String() string {
	switch mode {
	case BuildModeUnset:
		return "" // avoid showing a default in usage message
	case BuildModeExe:
		return "exe"
	case BuildModePIE:
		return "pie"
	case BuildModeCArchive:
		return "c-archive"
	case BuildModeCShared:
		return "c-shared"
	case BuildModeShared:

View on GitHub (pinned to b6b368adc5)

Solutions

Check the Go documentation for buildmode platform support matrix
Switch to a supported GOOS/GOARCH for the desired buildmode (e.g. use GOOS=linux for -buildmode=shared)
Use a different buildmode that is supported on your target platform
If the platform should support it, verify you are using a recent enough Go version

Example fix

# before (shared mode not supported on macOS)
GOOS=darwin GOARCH=amd64 go build -buildmode=shared ./mylib

# after (shared mode supported on Linux)
GOOS=linux GOARCH=amd64 go build -buildmode=shared ./mylib

Defensive patterns

Strategy: validation

Validate before calling

// Check platform support before setting buildmode
// This mirrors the linker's internal platform.BuildModeSupported check
func isBuildModeSupported(mode, goos, goarch string) bool {
    // Consult the Go platform support table
    // e.g. -buildmode=shared only on linux/*
    // e.g. -buildmode=plugin on linux/amd64, linux/arm64, darwin/amd64, etc.
    return platform.BuildModeSupported("gc", mode, goos, goarch)
}

Try / catch

// Catch unsupported buildmode and suggest alternatives
if err := mode.Set(s); err != nil {
    if strings.Contains(err.Error(), "not supported") {
        fmt.Fprintf(os.Stderr, "%v\nTry a different GOOS/GOARCH or buildmode.\n", err)
    }
    return err
}

Prevention

Consult the Go documentation for the buildmode/platform support matrix
Test buildmode compatibility in CI for each target platform before relying on it
Keep a reference of which buildmodes work on which GOOS/GOARCH combinations

When it happens

Trigger: After successfully parsing the buildmode string into a BuildMode constant, the linker calls platform.BuildModeSupported("gc", s, buildcfg.GOOS, buildcfg.GOARCH). If this returns false, the error includes the buildmode, OS, and architecture to help the user identify the incompatibility.

Common situations: Using -buildmode=shared on macOS or Windows (only supported on Linux); using -buildmode=plugin on an unsupported architecture; requesting PIE on a platform that does not support it; cross-compiling to a target where the buildmode is not implemented.

Related errors

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