unsupported version of the configuration: %q See https://gol

Error message

unsupported version of the configuration: %q See https://golangci-lint.run/docs/product/migration-guide for migration instructions

What it means

checkConfigurationVersion requires config files (when a config dir is present) to declare version: '2'. Any other version string — missing, '1', or a typo — is rejected with a pointer to the migration guide, since v2 changed the config schema significantly.

Source

Thrown at pkg/config/loader.go:155

	if l.fs == nil {
		return
	}

	l.appendStringSlice("enable", &l.cfg.Linters.Enable)
	l.appendStringSlice("disable", &l.cfg.Linters.Disable)
	l.appendStringSlice("build-tags", &l.cfg.Run.BuildTags)
}

func (l *Loader) appendStringSlice(name string, current *[]string) {
	if l.fs.Changed(name) {
		val, _ := l.fs.GetStringSlice(name)
		*current = append(*current, val...)
	}
}

func (l *Loader) checkConfigurationVersion() error {
	if l.cfg.GetConfigDir() != "" && l.cfg.Version != "2" {
		return fmt.Errorf("unsupported version of the configuration: %q "+
			"See https://golangci-lint.run/docs/product/migration-guide for migration instructions", l.cfg.Version)
	}

	return nil
}

func (l *Loader) handleGoVersion() {
	if l.cfg.Run.Go == "" {
		l.cfg.Run.Go = detectGoVersion(context.Background(), l.log)
	}

	l.cfg.Linters.Settings.Govet.Go = l.cfg.Run.Go

	l.cfg.Linters.Settings.ParallelTest.Go = l.cfg.Run.Go

	l.cfg.Linters.Settings.GoFumpt.LangVersion = l.cfg.Run.Go
	l.cfg.Formatters.Settings.GoFumpt.LangVersion = l.cfg.Run.Go

View on GitHub (pinned to ed7a235d2d)

Solutions

Add or set version: "2" at the top of the config file after migrating it
Run 'golangci-lint migrate' to convert a v1 config to v2 automatically
Follow https://golangci-lint.run/docs/product/migration-guide for manual migration

Example fix

# before
linters:
  enable:
    - revive
# after
version: "2"
linters:
  enable:
    - revive

Defensive patterns

Strategy: validation

Validate before calling

data, _ := os.ReadFile(cfgPath)
var m map[string]any
_ = yaml.Unmarshal(data, &m)
if m["version"] != "2" {
	return fmt.Errorf("config must declare version: \"2\" (run golangci-lint migrate)")
}

Try / catch

if err := loader.Load(ctx); err != nil {
	if strings.Contains(err.Error(), "unsupported version") {
		log.Fatal("run 'golangci-lint migrate' to upgrade config to v2")
	}
}

Prevention

Always declare version: "2" in v2-era configs
Run 'golangci-lint migrate' once when upgrading from v1
Use exactly "2", not "2.0" or "v2"

When it happens

Trigger: Running golangci-lint v2 with a config lacking 'version: "2"' or with version set to anything else; running v2 against a legacy v1 .golangci.yml.

Common situations: Upgrading golangci-lint from v1 to v2 without migrating the config; hand-rolled configs forgetting the version key; version set to '2.0' instead of '2'.

Related errors

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