golangci/golangci-lint · error

settings key %q must be valid analyzer name, valid analyzers

Error message

settings key %q must be valid analyzer name, valid analyzers: %v

What it means

Raised by Linter.configure in golangci-lint when a key in the settings map (lnt.cfg) does not match any registered analyzer name. The library builds an analyzersMap from all enabled analyzers and rejects unknown keys, listing the valid analyzer names. It guards against misconfigured settings sections that would otherwise be silently ignored.

Source

Thrown at pkg/goanalysis/linter.go:171

		if err := f.Value.Set(valueToString(v)); err != nil {
			return fmt.Errorf("failed to set analyzer setting %q with value %q: %w", k, v, err)
		}
	}

	return nil
}

func (lnt *Linter) configure() error {
	analyzersMap := map[string]*analysis.Analyzer{}
	for _, a := range lnt.analyzers {
		analyzersMap[a.Name] = a
	}

	for analyzerName, analyzerSettings := range lnt.cfg {
		a := analyzersMap[analyzerName]
		if a == nil {
			return fmt.Errorf("settings key %q must be valid analyzer name, valid analyzers: %v",
				analyzerName, lnt.allAnalyzerNames())
		}

		if err := lnt.configureAnalyzer(a, analyzerSettings); err != nil {
			return fmt.Errorf("failed to configure analyzer %s: %w", analyzerName, err)
		}
	}

	return nil
}

func (lnt *Linter) preRun(lintCtx *linter.Context) error {
	if err := analysis.Validate(lnt.analyzers); err != nil {
		return fmt.Errorf("failed to validate analyzers: %w", err)
	}

	if err := lnt.configure(); err != nil {
		return fmt.Errorf("failed to configure analyzers: %w", err)

View on GitHub (pinned to ed7a235d2d)

Solutions

  1. Rename the settings key to one of the valid analyzers listed in the error message
  2. Remove the stale settings block for a linter that no longer exists or is not enabled
  3. Run `golangci-lint help linters` to confirm the exact analyzer name
  4. If a linter was renamed in a newer version, migrate the settings to the new name

Example fix

# before (.golangci.yml)
settings:
  golint:
    min-confidence: 0.8
# after
settings:
  revive:
    min-confidence: 0.8
Defensive patterns

Strategy: validation

Validate before calling

validNames := map[string]bool{"staticcheck": true, "revive": true /* ... */}
for key := range cfg.Settings {
    if !validNames[key] {
        return fmt.Errorf("settings key %q is not a valid analyzer name", key)
    }
}

Try / catch

if err := golangciRun(cfg); err != nil {
    if strings.Contains(err.Error(), "must be valid analyzer name") {
        fmt.Fprintf(os.Stderr, "unknown analyzer in settings: %v\n", err)
        os.Exit(1)
    }
    return err
}

Prevention

When it happens

Trigger: A .golangci.yml settings (or golangci-lint config) block whose top-level key is not a real analyzer name — e.g. a misspelled analyzer, a linter that was removed/renamed, or settings placed under a wrong section.

Common situations: Upgrading golangci-lint where a linter was deprecated/renamed (old settings key left behind), typos like `gosimple` vs `staticcheck` merges, or copy-pasted config from another project with different enabled linters.

Related errors

AI-assisted analysis of golangci/golangci-lint@ed7a235d2d (2026-09-02). Data as JSON: /api/errors/34c5e6f80bf02302. Report an issue: GitHub.