golangci/golangci-lint · error

failed to get doc (%s) of file %s: %w

Error message

failed to get doc (%s) of file %s: %w

What it means

While deciding whether to pass an issue, the generated-file exclusion processor tries to detect if the file is autogenerated by reading its doc comment. The matcher returned an error (e.g. the file could not be parsed or read), so shouldPassIssue aborts with this error naming the mode and file instead of silently filtering or passing the issue.

Source

Thrown at pkg/result/processors/exclusion_generated_file_filter.go:70

func (p *GeneratedFileFilter) shouldPassIssue(issue *result.Issue) (bool, error) {
	if filepath.Base(issue.FilePath()) == "go.mod" {
		return true, nil
	}

	// The file is already known.
	fs := p.fileSummaryCache[issue.FilePath()]
	if fs != nil {
		return !fs.generated, nil
	}

	fs = &fileSummary{}
	p.fileSummaryCache[issue.FilePath()] = fs

	var err error
	fs.generated, err = p.matcher.IsGeneratedFile(issue.FilePath(), nil)
	if err != nil {
		return false, fmt.Errorf("failed to get doc (%s) of file %s: %w", p.mode, issue.FilePath(), err)
	}

	p.debugf("file %q is generated: %t", issue.FilePath(), fs.generated)

	// don't report issues for autogenerated files
	return !fs.generated, nil
}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Fix the syntax error in the reported file so it parses as Go
2. Restore/verify the file exists and is readable at the reported path
3. Re-run the lint to clear stale results if the file was deleted concurrently
4. Exclude the problematic file from linting via run.skip-files if it is not valid Go

// Go: ensure the file parses before filtering relies on generated detection
fset := token.NewFileSet()
if _, err := parser.ParseFile(fset, path, nil, parser.PackageClauseOnly); err != nil {
    log.Printf("skipping unparseable file %s: %v", path, err)
}

pass, err := filter.ShouldPassIssue(issue)
if err != nil {
    log.Printf("generated-file detection failed, keeping issue: %v", err)
    pass = true
}

When it happens

Trigger: shouldPassIssue is invoked for an issue whose file fails IsGeneratedFile — the file is unreadable, deleted between scan and filtering, or contains invalid Go syntax so the parser fails.

Common situations: Stale file references after files were removed mid-run; generated files with syntax errors checked in; permissions problems on source files; excluding files with non-Go extensions matched by the linter.

Related errors

• failed to parse file: %w
• the configuration contains invalid elements
• unsupported configuration format
• the configuration contains invalid elements
• parallel golangci-lint is running

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