golangci/golangci-lint · error

invalid version of the configuration: %q

Error message

invalid version of the configuration: %q

What it means

The fmt command's preRunE requires the configuration schema version to be "2" whenever a config directory is set (c.cfg.GetConfigDir() != ""). The formatters feature only supports the v2 config schema; an older v1 (or otherwise invalid) version string makes fmt refuse to run.

Source

Thrown at pkg/commands/fmt.go:95

	return c
}

func (c *fmtCommand) persistentPreRunE(cmd *cobra.Command, args []string) error {
	c.log.Infof("%s", c.buildInfo.String())

	loader := config.NewFormattersLoader(c.log.Child(logutils.DebugKeyConfigReader), c.viper, cmd.Flags(), c.opts.LoaderOptions, c.cfg, args)

	err := loader.Load(config.LoadOptions{CheckDeprecation: true, Validation: true})
	if err != nil {
		return fmt.Errorf("can't load config: %w", err)
	}

	return nil
}

func (c *fmtCommand) preRunE(_ *cobra.Command, _ []string) error {
	if c.cfg.GetConfigDir() != "" && c.cfg.Version != "2" {
		return fmt.Errorf("invalid version of the configuration: %q", c.cfg.Version)
	}

	metaFormatter, err := goformatters.NewMetaFormatter(c.log, &c.cfg.Formatters, &c.cfg.Run)
	if err != nil {
		return fmt.Errorf("failed to create meta-formatter: %w", err)
	}

	matcher := processors.NewGeneratedFileMatcher(c.cfg.Formatters.Exclusions.Generated)

	opts, err := goformat.NewRunnerOptions(c.cfg, c.opts.diff, c.opts.diffColored, c.opts.stdin)
	if err != nil {
		return fmt.Errorf("build walk options: %w", err)
	}

	c.runner = goformat.NewRunner(c.log, metaFormatter, matcher, opts)

	return nil
}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Add `version: "2"` to the top of your config file and migrate settings to the new schema.
2. Use `golangci-lint migrate` (if available) to convert a v1 config to v2.
3. If you must keep the v1 config, do not use the `fmt` command / pin an older golangci-lint version.

Example fix

// before (.golangci.yml)
linters:
  enable: [gofmt]
// after
version: "2"
formatters:
  enable: [gofmt]

// before invoking fmt, check the config declares v2
data, _ := os.ReadFile(configPath)
if !regexp.MustCompile(`(?m)^\s*version:\s*["']?2["']?\s*$`).Match(data) {
  return fmt.Errorf("%s must contain `version: \"2\"` for the fmt command", configPath)
}

if err := fmtCmd.Run(); err != nil {
  if strings.Contains(err.Error(), "invalid version of the configuration") {
    log.Fatal("migrate config to schema v2 (add `version: \"2\"` and move formatter settings)")
  }
  return err
}

When it happens

Trigger: Running `golangci-lint fmt` with a config file lacking `version: "2"` (or containing another value) while a config dir is detected — i.e., using a v1 .golangci.yml with the new formatters command.

Common situations: Upgraded golangci-lint to a release with the v2 schema but kept an old v1 config file; copied a legacy config; hand-edited the version key.

Related errors

• the configuration contains invalid elements
• unsupported configuration format
• the configuration contains invalid elements
• can't set severity rule option: no default severity defined
• severity should be set

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