What causes "gci: creating formatter: %w" in golangci/golangci-lint?

Fix settings.gci.sections: each entry must be 'standard', 'default', 'prefix(module/path)', 'blank-imports', etc.

gci: creating formatter: %w

Error message

gci: creating formatter: %w

What it means

When gci is in the enabled formatters list, NewMetaFormatter constructs the gci formatter from its settings; if gci.New fails, the error is wrapped as 'gci: creating formatter: %w'. The root cause is an invalid gci configuration (bad sections or unparseable options), not golangci-lint itself.

Source

Thrown at pkg/goformatters/meta_formatter.go:53

	}

	if slices.Contains(cfg.Enable, gofumpt.Name) {
		m.formatters = append(m.formatters, gofumpt.New(&cfg.Settings.GoFumpt, runCfg.Go))
	}

	if slices.Contains(cfg.Enable, goimports.Name) {
		m.formatters = append(m.formatters, goimports.New(&cfg.Settings.GoImports))
	}

	if slices.Contains(cfg.Enable, swaggo.Name) {
		m.formatters = append(m.formatters, swaggo.New())
	}

	// gci is a last because the only goal of gci is to handle imports.
	if slices.Contains(cfg.Enable, gci.Name) {
		formatter, err := gci.New(&cfg.Settings.Gci)
		if err != nil {
			return nil, fmt.Errorf("gci: creating formatter: %w", err)
		}

		m.formatters = append(m.formatters, formatter)
	}

	// golines calls `format.Source()` internally so no need to format after it.
	if slices.Contains(cfg.Enable, golines.Name) {
		m.formatters = append(m.formatters, golines.New(&cfg.Settings.GoLines))
	}

	return m, nil
}

func (m *MetaFormatter) Format(filename string, src []byte) []byte {
	if len(m.formatters) == 0 {
		data, err := format.Source(src)
		if err != nil {
			m.log.Warnf("(fmt) formatting file %s: %v", filename, err)

View on GitHub (pinned to ed7a235d2d)

Solutions

Fix settings.gci.sections: each entry must be 'standard', 'default', 'prefix(module/path)', 'blank-imports', etc.
Verify prefix module paths are valid and parentheses are balanced
Test the gci config standalone: gci diff --section standard .
Check the gci version bundled with your golangci-lint for syntax changes and adjust

Example fix

# before
formatters:
  enable: [gci]
  settings:
    gci:
      sections:
        - prefix(github.com/myorg
# after
formatters:
  enable: [gci]
  settings:
    gci:
      sections:
        - standard
        - default
        - prefix(github.com/myorg)

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/maratori/gci"
for _, s := range cfg.LintersSettings.Gci.Sections {
    if s != "standard" && s != "default" && s != "blank-imports" && s != "comment" && s != "cgo" && !strings.HasPrefix(s, "prefix(") {
        return fmt.Errorf("invalid gci section %q", s)
    }
    if strings.HasPrefix(s, "prefix(") && !strings.HasSuffix(s, ")") {
        return fmt.Errorf("malformed gci prefix section %q", s)
    }
}

Try / catch

if err := golangci.Run(); err != nil {
    if strings.Contains(err.Error(), "gci: creating formatter") {
        fmt.Fprintln(os.Stderr, "check linters-settings.gci sections syntax (standard|default|prefix(mod))")
        os.Exit(1)
    }
    return err
}

Prevention

Test gci config standalone with 'gci diff --section ...' before adding to .golangci.yml
Keep sections as standard, default, then prefix(...) entries
Re-check gci section syntax when upgrading golangci-lint

When it happens

Trigger: formatters.enable contains 'gci' AND settings.gci contains invalid values, e.g. malformed custom sections like 'prefix(github.com' (unbalanced paren) or an unknown section keyword, causing gci.New to return an error.

Common situations: Copying gci sections from another project with wrong syntax, forgetting the 'standard' or 'default' section, typos like 'PrefiX(...)', or gci option shape changes after upgrading golangci-lint's bundled gci.

Related errors

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