{"record":{"id":"c8256b9a017b8a3d","repo":"golang/go","slug":"invalid-version-q-c8256b","errorCode":null,"errorMessage":"invalid version %q","messagePattern":"invalid version %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/link/internal/ld/macho.go","lineNumber":433,"sourceCode":"func (f *macVersionFlag) Set(s string) error {\n\tvar parsed macVersionFlag\n\tnums := strings.Split(s, \".\")\n\tif len(nums) > 3 {\n\t\tgoto Error\n\t}\n\tfor i, num := range nums {\n\t\tn, err := strconv.Atoi(num)\n\t\tif err != nil || n < 0 || n > 0xFF {\n\t\t\tgoto Error\n\t\t}\n\t\tparsed[i] = byte(n)\n\t}\n\t// success, now modify f\n\t*f = parsed\n\treturn nil\n\nError:\n\treturn fmt.Errorf(\"invalid version %q\", s)\n}\n\nfunc (f *macVersionFlag) version() uint32 {\n\treturn uint32(f[0])<<16 | uint32(f[1])<<8 | uint32(f[2])\n}\n\nvar (\n\t// On advice from Apple engineers, we keep macOS set to the\n\t// oldest supported macOS version but keep macSDK to the newest\n\t// tested OS/SDK version. If these defaults are not good enough,\n\t// the -macos and -macsdk linker flags can override them.\n\t// For past problems involving these values, see\n\t//\tgo.dev/issue/30488\n\t//\tgo.dev/issue/56784\n\t//\tgo.dev/issue/77917\n\tmacOS  = macVersionFlag{13, 0, 0}\n\tmacSDK = macVersionFlag{26, 2, 0}\n)","sourceCodeStart":415,"sourceCodeEnd":451,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/link/internal/ld/macho.go#L415-L451","documentation":"The `-macos` and `-macsdk` linker flags (exposed via `-ldflags='-X cmd/link/internal/ld.macos=...'`-style mechanisms, or the internal `macVersionFlag.Set`) parse a dot-separated version string into exactly three byte-sized components (major.minor.patch). Parsing fails if the string is not three dot-separated integers, or if any component is outside 0–255, because macOS encodes the version in a single uint32 as `major<<16 | minor<<8 | patch`.","triggerScenarios":"Passing `-ldflags='-macos 10.15.7.1'` (four components), `-macos 999.0` (>255), `-macos latest` (non-numeric), or `-macos 10` (one component). Also triggered by automation that interpolates an SDK version string with extra fields (e.g. a build number or arch suffix).","commonSituations":"CI scripts deriving `-macos` from `xcrun --show-sdk-version` and forgetting to trim a trailing build identifier; hardcoding a version that exceeds 255 in one field after a macOS release; copy-pasting an iOS version string into a macOS flag.","solutions":["Use exactly three dot-separated integers in the range 0–255, e.g. `-macos 11.0.0`.","Trim any suffix from the SDK version before passing it: strip build numbers, arch tags, and trailing dots.","If you do not need to override the default, remove the `-macos`/`-macsdk` flag entirely — the linker ships sane defaults.","Validate the version string with a shell check (regex `^[0-9]{1,3}(\\.[0-9]{1,3}){2}$`) before invoking `go build`."],"exampleFix":"# before\ngo build -ldflags='-macos 13.6.1-build42' ./...\n\n# after\nMACOS=$(xcrun --show-sdk-version | cut -d. -f1-3)\ngo build -ldflags=\"-macos $MACOS\" ./...","handlingStrategy":"validation","validationCode":"# Validate a macOS version string before passing it to -ldflags\nvalidate_macos_version() {\n  local v=\"$1\"\n  if ! printf '%s' \"$v\" | grep -Eq '^[0-9]{1,3}(\\.[0-9]{1,3}){2}$'; then\n    echo \"invalid macOS version: $v (need N.N.N, each 0-255)\" >&2\n    return 1\n  fi\n  IFS=. read -r a b c <<<\"$v\"\n  for n in \"$a\" \"$b\" \"$c\"; do [ \"$n\" -le 255 ] || { echo \"$n > 255\" >&2; return 1; }; done\n}\nvalidate_macos_version \"$MACOS_VERSION\" || exit 1","typeGuard":"// Type guard for a Go-side version-string helper\nfunc isValidMacVersion(s string) bool {\n    parts := strings.Split(s, \".\")\n    if len(parts) != 3 { return false }\n    for _, p := range parts {\n        n, err := strconv.Atoi(p)\n        if err != nil || n < 0 || n > 0xFF { return false }\n    }\n    return true\n}","tryCatchPattern":"# In CI: validate before building; fall back to default if invalid\nif validate_macos_version \"$MACOS_VERSION\"; then\n  go build -ldflags=\"-macos $MACOS_VERSION\" ./...\nelse\n  echo 'invalid version; using linker default' >&2\n  go build ./...\nfi","preventionTips":["Always pass exactly three dot-separated integers (0–255) to `-macos`/`-macsdk`.","Trim build numbers and suffixes from `xcrun --show-sdk-version` output.","If unsure, omit the flag and use the linker's tested defaults.","Validate version strings in CI with a regex."],"tags":["linker","go-toolchain","macos","versioning","ldflags"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}