golangci/golangci-lint · error

failed to create meta-formatter: %w

Error message

failed to create meta-formatter: %w

What it means

In fmt's preRunE, goformatters.NewMetaFormatter (which sets up the selected formatters, their options and exclusions) failed. The wrapping "failed to create meta-formatter" indicates formatter settings could not be turned into runnable formatter instances.

Source

Thrown at pkg/commands/fmt.go:100

	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
}

func (c *fmtCommand) execute(_ *cobra.Command, args []string) error {
	paths := cleanArgs(args)

	c.log.Infof("Formatting Go files...")

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Read the wrapped cause: it identifies which formatter or option failed; fix that config entry.
2. Verify formatter names against `golangci-lint formatters` output for your version.
3. Ensure custom plugin formatters are built into the binary (via `golangci-lint custom`) before use.
4. Remove unknown formatter entries from the `formatters:` section.

Example fix

// before (.golangci.yml)
formatters:
  enable: [gofmpt]
// after
formatters:
  enable: [gofumpt]

// check formatter names are known before running fmt
out, err := exec.Command("golangci-lint", "formatters").CombinedOutput()
if err != nil { return err }
for _, name := range cfg.Formatters.Enable {
  if !strings.Contains(string(out), name) {
    return fmt.Errorf("unknown formatter %q", name)
  }
}

if err := fmtCmd.Run(); err != nil {
  if strings.Contains(err.Error(), "failed to create meta-formatter") {
    log.Fatalf("check formatters section: %v", errors.Unwrap(err))
  }
  return err
}

When it happens

Trigger: Running `golangci-lint fmt` where the `formatters` config section references an unknown formatter name, has invalid formatter options, or a formatter plugin fails to initialize.

Common situations: Typo in a formatter name (e.g. `gofumports` vs `gofumpt`); invalid options under a formatter's settings; a custom plugin formatter not registered/built into the binary.

Related errors

• build walk options: %w
• failed to process files: %w
• can't get enabled formatters: %w
• %s is not a formatter
• unable to open file %s: %w

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