What causes "-var: %q is not a valid identifier" in golang/go?

Use a valid Go identifier for -var (letters/digits/underscore, not starting with a digit)

-var: %q is not a valid identifier

Error message

-var: %q is not a valid identifier

What it means

Thrown by 'go tool cover' parseFlags when -var is set to a string that is not a valid Go identifier (checked via token.IsIdentifier). The -var flag names the coverage counter variable injected into instrumented source, so it must be a legal Go identifier to produce compilable code.

Source

Thrown at src/cmd/cover/cover.go:147

}

// parseFlags sets the profile and counterStmt globals and performs validations.
func parseFlags() error {
	profile = *htmlOut
	if *funcOut != "" {
		if profile != "" {
			return fmt.Errorf("too many options")
		}
		profile = *funcOut
	}

	// Must either display a profile or rewrite Go source.
	if (profile == "") == (*mode == "") {
		return fmt.Errorf("too many options")
	}

	if *varVar != "" && !token.IsIdentifier(*varVar) {
		return fmt.Errorf("-var: %q is not a valid identifier", *varVar)
	}

	if *mode != "" {
		switch *mode {
		case "set":
			counterStmt = setCounterStmt
			cmode = coverage.CtrModeSet
		case "count":
			counterStmt = incCounterStmt
			cmode = coverage.CtrModeCount
		case "atomic":
			counterStmt = atomicCounterStmt
			cmode = coverage.CtrModeAtomic
		case "regonly":
			counterStmt = nil
			cmode = coverage.CtrModeRegOnly
		case "testmain":
			counterStmt = nil

View on GitHub (pinned to b6b368adc5)

Solutions

Use a valid Go identifier for -var (letters/digits/underscore, not starting with a digit)
Leave -var unset to use the default GoCover
Validate the name in your build script with a regex like ^[A-Za-z_][A-Za-z0-9_]*$ before passing it

Example fix

# before
go tool cover -mode=set -var=Cov-Count file.go
# after
go tool cover -mode=set -var=CovCount file.go

Defensive patterns

Strategy: validation

Validate before calling

import re
name = "CovCount"
if not re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', name):
    raise SystemExit(f"invalid -var identifier: {name}")

Prevention

Validate identifier names with a regex before passing to -var
Prefer the default GoCover unless you need a custom name

When it happens

Trigger: `go tool cover -mode=set -var=1Coverage` or `-var=Cov-Var` or `-var=` (empty after the guard) — any value failing token.IsIdentifier while non-empty.

Common situations: Variable names starting with a digit, containing hyphens/spaces/punctuation, or using reserved symbols. Custom build scripts templating the -var value unsafely.

Related errors

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