What causes "failed to process files: %w" in golangci/golangci-lint?

Read the wrapped cause to find the specific file or formatter that failed.

failed to process files: %w

Error message

failed to process files: %w

What it means

fmt's execute step calls c.runner.Run(paths) which walks the given paths, applies the enabled formatters, and (optionally) writes or diffs the results. Any failure during this processing phase is wrapped as "failed to process files".

Source

Thrown at pkg/commands/fmt.go:122

	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...")

	err := c.runner.Run(paths)
	if err != nil {
		return fmt.Errorf("failed to process files: %w", err)
	}

	return nil
}

func (c *fmtCommand) persistentPostRun(_ *cobra.Command, _ []string) {
	if c.runner.ExitCode() != 0 {
		os.Exit(c.runner.ExitCode())
	}
}

func cleanArgs(args []string) []string {
	if len(args) == 0 {
		return []string{"."}
	}

	var expanded []string
	for _, arg := range args {

View on GitHub (pinned to ed7a235d2d)

Solutions

Read the wrapped cause to find the specific file or formatter that failed.
Fix Go syntax errors in the reported files (formatters require parseable source).
Check file/directory read-write permissions for the paths passed.
Exclude problematic generated/vendored files via formatters.exclusions and re-run.

Example fix

// before
golangci-lint fmt ./broken/   # contains malformed .go file
// after
gofmt -l ./broken/            # locate the syntax error, fix it, then re-run fmt

Defensive patterns

Strategy: validation

Validate before calling

// ensure all target files parse before formatting
for _, f := range goFiles {
  if _, err := parser.ParseFile(token.NewFileSet(), f, nil, parser.ParseComments); err != nil {
    return fmt.Errorf("unparseable file %s: %w", f, err)
  }
}
// ensure paths are readable
if err := filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
  if err != nil { return err }
  return nil
}); err != nil { return err }

Try / catch

if err := fmtCmd.Run(); err != nil {
  if strings.Contains(err.Error(), "failed to process files") {
    log.Fatalf("fix the offending file/formatter: %v", errors.Unwrap(err))
  }
  return err
}

Prevention

Run `gofmt -l`/`go build ./...` first to catch syntax errors before formatting.
Exclude generated and vendored code via formatters.exclusions.
Check permissions on target directories, especially in CI with restricted users.
Format in small batches to isolate which file triggers a formatter failure.

When it happens

Trigger: Running `golangci-lint fmt` where the runner fails while walking paths (unreadable dirs/files, permission errors) or an individual formatter crashes/errors on some Go source.

Common situations: Formatting files with syntax errors that a formatter cannot parse; unreadable directories (permissions); filesystem errors; a formatter panicking on unusual code.

Related errors

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