What causes "enabled check %q doesn't exist, see %s's documentation" in golangci/golangci-lint?

Correct the check name in settings.gocritic.enabled-checks (match gocritic's exact check name)

enabled check %q doesn't exist, see %s's documentation

Error message

enabled check %q doesn't exist, see %s's documentation

What it means

The gocritic settings wrapper validates that each check name in settings.gocritic.enabled-checks is a real gocritic check. An unknown check name aborts the run with this error, pointing at gocritic's documentation.

Source

Thrown at pkg/golinters/gocritic/gocritic_settings.go:349

	for _, tag := range s.EnabledTags {
		if !s.allChecksByTag.has(tag) {
			return fmt.Errorf("enabled tag %q doesn't exist, see %s's documentation", tag, linterName)
		}
	}

	for _, tag := range s.DisabledTags {
		if !s.allChecksByTag.has(tag) {
			return fmt.Errorf("disabled tag %q doesn't exist, see %s's documentation", tag, linterName)
		}
	}

	return nil
}

func (s *settingsWrapper) validateCheckerNames() error {
	for _, check := range s.EnabledChecks {
		if !s.allChecks.has(check) {
			return fmt.Errorf("enabled check %q doesn't exist, see %s's documentation", check, linterName)
		}
	}

	for _, check := range s.DisabledChecks {
		if !s.allChecks.has(check) {
			return fmt.Errorf("disabled check %q doesn't exist, see %s documentation", check, linterName)
		}
	}

	for check := range s.SettingsPerCheck {
		lcName := strings.ToLower(check)

		if !s.allChecksLowerCased.has(lcName) {
			return fmt.Errorf("invalid check settings: check %q doesn't exist, see %s documentation", check, linterName)
		}

		if !s.inferredEnabledChecksLowerCased.has(lcName) {
			s.logger.Warnf("%s: settings were provided for disabled check %q", check, linterName)

View on GitHub (pinned to ed7a235d2d)

Solutions

Correct the check name in settings.gocritic.enabled-checks (match gocritic's exact check name)
List available checks for your gocritic version and pick a valid name
Remove the unknown check from enabled-checks
Upgrade or downgrade golangci-lint so the check exists in that gocritic version

Example fix

// before (.golangci.yml)
settings:
  gocritic:
    enabled-checks:
      - rangeValCopyz
// after
settings:
  gocritic:
    enabled-checks:
      - rangeValCopy

Defensive patterns

Strategy: validation

Validate before calling

const knownChecks = new Set(getGocriticChecksForVersion()) // from 'golangci-lint help' or docs
const bad = cfg.settings.gocritic['enabled-checks'].filter(c => !knownChecks.has(c))
if (bad.length) throw new Error(`unknown gocritic checks: ${bad.join(', ')}`)

Type guard

const isKnownGocriticCheck = (c) => knownChecks.has(c)

Prevention

Copy check names exactly from gocritic's documentation, never by memory
Run 'golangci-lint config verify' in CI to catch stale names
Re-validate check names after each golangci-lint/gocritic upgrade

When it happens

Trigger: Config contains settings.gocritic.enabled-checks with a check name not present in gocritic's check registry (allChecks.has(check) fails): typo, removed check, or check from another linter.

Common situations: Misspelled check names like 'singleCaseSwitch' vs 'singleCaseSwitch' casing variants, using checks removed in a gocritic upgrade, copying check names from staticcheck.

Related errors

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