golang/go · error

invalid headtype: %q

Error message

invalid headtype: %q

What it means

HeadType is an enum representing the output binary format (ELF, Mach-O, PE, etc.), selected based on the target GOOS. `HeadType.Set` maps OS name strings to their corresponding head type. When the provided string does not match any known OS, the error is returned. This is typically set internally by the linker from GOOS, but can be overridden via flags.

Source

Thrown at src/cmd/internal/objabi/head.go:81

		*h = Hfreebsd
	case "js":
		*h = Hjs
	case "linux", "android":
		*h = Hlinux
	case "netbsd":
		*h = Hnetbsd
	case "openbsd":
		*h = Hopenbsd
	case "plan9":
		*h = Hplan9
	case "illumos", "solaris":
		*h = Hsolaris
	case "wasip1":
		*h = Hwasip1
	case "windows":
		*h = Hwindows
	default:
		return fmt.Errorf("invalid headtype: %q", s)
	}
	return nil
}

func (h HeadType) String() string {
	switch h {
	case Haix:
		return "aix"
	case Hdarwin:
		return "darwin"
	case Hdragonfly:
		return "dragonfly"
	case Hfreebsd:
		return "freebsd"
	case Hjs:
		return "js"
	case Hlinux:
		return "linux"

View on GitHub (pinned to b6b368adc5)

Solutions

1. Verify the headtype string matches a supported GOOS exactly (case-sensitive: lowercase).
2. Check `go tool dist list` to confirm the target OS is supported by your Go version.
3. Remove any custom `-H` flag and let the toolchain infer the head type from GOOS/GOARCH.

Example fix

// before
$ go tool link -H gnulinux main.o

// after
$ go tool link -H linux main.o
// or omit the flag entirely:
$ go build main.go

// Validate GOOS string before setting headtype
var validHeadTypes = map[string]bool{
    "aix": true, "darwin": true, "dragonfly": true, "freebsd": true,
    "linux": true, "netbsd": true, "openbsd": true, "plan9": true,
    "illumos": true, "solaris": true, "wasip1": true, "windows": true,
}
func isValidHeadType(s string) bool {
    return validHeadTypes[s]
}

When it happens

Trigger: Setting `-H` or `--headtype` (or equivalent) to a string that is not in the recognized list: aix, darwin, dragonfly, freebsd, linux, netbsd, openbsd, plan9, illumos, solaris, wasip1, windows. Also triggered when an internal code path passes an unsupported GOOS string.

Common situations: Using a custom build wrapper that injects a `-H` value. Building for an experimental or unsupported target. Typo in the headtype name. Using a Go version that does not yet support a particular target OS.

Related errors

• corrupt archive
• truncated archive
• corrupt object file
• fail to seek
• fail to seek

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