golangci-lint Config Errors - Fix .golangci.yml Failures in CI

golangci-lint reads .golangci.yml/.golangci.toml before linting. A config that names a removed linter, uses a key the current version dropped, or omits the required config version makes the tool fail to start - so the lint gate errors without ever inspecting your code.

What this error means

A golangci-lint run step fails at startup with unknown linters: ..., unsupported version of the configuration, or a YAML schema error pointing at a key in .golangci.yml. The failure is about the config file, not your Go code.

golangci-lint output

level=error msg="[config_reader] unknown linters: 'maligned', 'golint';
	run 'golangci-lint help linters' to see the list"
# or, after a v2 upgrade:
level=error msg="unsupported version of the configuration: ''"

Common causes

A removed or renamed linter in the config

A linter that was deprecated and deleted (e.g. golint, maligned, scopelint) is still listed under enable, so the config references a linter that no longer exists.

A config-schema or version mismatch

A golangci-lint upgrade changed the config schema (or now requires a top-level version:); an old config no longer validates against the new version.

How to fix it

Validate the config and drop unknown linters

Verify the config against the installed version and remove linters it does not know.

Terminal

golangci-lint config verify
golangci-lint help linters   # see which linters exist in this version

Pin the golangci-lint version to your config

Match the action version to the config schema so CI and the config agree.

.github/workflows/ci.yml

- uses: golangci/golangci-lint-action@v6
  with:
    version: v1.59.1

Migrate the config on a major upgrade

Read the golangci-lint migration notes for the new major version.
Add the required version: key and replace removed linters with their successors.
Run golangci-lint config verify until it passes.

How to prevent it

Pin the golangci-lint version in CI, not latest.
Run golangci-lint config verify so config errors fail fast and locally.
Update .golangci.yml when upgrading across major versions.