golangci/golangci-lint · error

unknown linters: '%v', run 'golangci-lint help linters' to s

Error message

unknown linters: '%v', run 'golangci-lint help linters' to see the list of supported linters

What it means

validateLintersNames checks every linter name requested via config (`linters.enable`, CLI flags, presets) against the registry of known linters and formatters. If any name is not registered, golangci-lint aborts before running and lists all unknown names. This guards against silent no-op configuration from typos or removed linters.

Source

Thrown at pkg/lint/lintersdb/validator.go:64

	for _, name := range cfg.Disable {
		lcs := v.m.GetLinterConfigs(name)
		if len(lcs) == 0 {
			unknownNames = append(unknownNames, name)
			continue
		}

		for _, lc := range lcs {
			if lc.IsDeprecated() && lc.Deprecation.Level > linter.DeprecationWarning {
				v.m.log.Warnf("The linter %q is deprecated (step 2) and deactivated. "+
					"It should be removed from the list of disabled linters. "+
					"https://golangci-lint.run/docs/product/roadmap/#linter-deprecation-cycle", lc.Name())
			}
		}
	}

	if len(unknownNames) > 0 {
		return fmt.Errorf("unknown linters: '%v', run 'golangci-lint help linters' to see the list of supported linters",
			strings.Join(unknownNames, ","))
	}

	return nil
}

func (v Validator) alternativeNamesDeprecation(cfg *config.Linters) error {
	if v.m.cfg.InternalTest || v.m.cfg.InternalCmdTest || os.Getenv(logutils.EnvTestRun) == "1" {
		return nil
	}

	altNames := map[string][]string{}
	for _, lc := range v.m.GetAllSupportedLinterConfigs() {
		for _, alt := range lc.AlternativeNames {
			altNames[alt] = append(altNames[alt], lc.Name())
		}
	}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Run `golangci-lint help linters` to list supported linters and compare with the names in your config/flags
2. Fix typos or remove the unknown name from .golangci.yml (`linters.enable`, `linters.disable`) or the --enable/--disable flags
3. If the linter was deprecated, check the deprecation roadmap (linked in the source) for its replacement
4. If it is a custom linter, ensure the plugin is built and referenced correctly in the `linters-settings`/plugin configuration for your golangci-lint build

Example fix

// before (.golangci.yml)
linters:
  enable:
    - goerr113   # unknown in current version
// after
linters:
  enable:
    - err113     # renamed linter

// Validate linter names before writing them into config / running:
// $ golangci-lint help linters
const known = new Set(execSync('golangci-lint help linters --format json').toString().trim().split('\n'));
const requested = ['gofmt', 'err113', 'my-typo'];
const unknown = requested.filter(n => !known.has(n));
if (unknown.length) throw new Error(`unknown linters: ${unknown.join(',')}`);

function isKnownLinter(name, knownSet) {
  return typeof name === 'string' && knownSet.has(name);
}

When it happens

Trigger: Running golangci-lint with `linters.enable`/`disable` entries (or `--enableX` flags) containing a name that no linter in the built-in registry or loaded plugins matches; the error message joins all unknown names with commas.

Common situations: Typo in .golangci.yml linter name; linter removed or renamed in a newer golangci-lint version (e.g. renamed deprecated linters); custom linter from a plugin not compiled/loaded; copying config between projects with different golangci-lint versions.

Related errors

• failed to get enabled linters: %w
• can't combine option --config and --no-config
• can't get enabled formatters: %w
• can't get enabled linters: %w
• failed to set analyzer setting %q with value %q: %w

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