invalid flag in %s: %s (see https://go.dev/s/invalidflag)

Error message

invalid flag in %s: %s (see https://go.dev/s/invalidflag)

What it means

Thrown by checkFlags at the `Bad:` label when a flag matches neither the allow list nor any valid-with-next-arg pattern (and is not rescued by CGO_*_ALLOW). It is the catch-all rejection for an unrecognized or disallowed cgo compiler/linker flag.

Source

Thrown at src/cmd/go/internal/work/security.go:466

				}

				// Permit -I= /path, -I $SYSROOT.
				if i+1 < len(list) && arg == "-I" {
					if (strings.HasPrefix(list[i+1], "=") || strings.HasPrefix(list[i+1], "$SYSROOT")) &&
						load.SafeArg(list[i+1][1:]) {
						i++
						continue Args
					}
				}

				if i+1 < len(list) {
					return fmt.Errorf("invalid flag in %s: %s %s (see https://go.dev/s/invalidflag)", source, arg, list[i+1])
				}
				return fmt.Errorf("invalid flag in %s: %s without argument (see https://go.dev/s/invalidflag)", source, arg)
			}
		}
	Bad:
		return fmt.Errorf("invalid flag in %s: %s (see https://go.dev/s/invalidflag)", source, arg)
	}
	return nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

Remove the unrecognized flag from the #cgo line or env var.
Replace it with an allow-listed equivalent if one exists.
Add an RE2-valid CGO_CFLAGS_ALLOW regexp that whitelists the specific flag (use sparingly; it bypasses the security check).
Use `go build -x` to confirm the resolved flag set.

Example fix

// before
// #cgo LDFLAGS: -Wl,-rpath,/opt/lib

// after
// #cgo LDFLAGS: -L/opt/lib

Defensive patterns

Strategy: validation

Validate before calling

// Flag tokens not on the allow list (illustrative subset)
allowedPrefix := []string{"-O", "-g", "-I", "-L", "-D", "-U", "-std=", "-Wall", "-Werror"}
flags := strings.Fields(os.Getenv("CGO_CFLAGS"))
for _, f := range flags {
    ok := false
    for _, p := range allowedPrefix { if strings.HasPrefix(f, p) { ok = true; break } }
    if !ok { log.Printf("warn: %s may be rejected by checkFlags", f) }
}

Prevention

Prefer allow-listed gcc/ld flags in #cgo directives.
Use CGO_CFLAGS_ALLOW (valid RE2) only for genuine exceptions.
Run `go vet`/`go build -x` early to catch rejected flags.

When it happens

Trigger: A #cgo CFLAGS/LDFLAGS line or CGO_CFLAGS/LDFLAGS env var contains a token that does not match any validCompilerFlags/validLinkerFlags entry and is not on the allow list — e.g. `-framework`, `-Wl,-rpath`, an exotic `-fplugin`, or an unsafe construct.

Common situations: Adding macOS-specific `-framework Foo` to a portable package; passing `-Wl,--as-needed` which is not on the allow list; vendored C code with toolchain-specific tuning flags; porting flags from a Makefile verbatim.

Related errors

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