What causes "failed to load package %s: %w" in golangci/golangci-lint?

Run `go clean -cache` to clear a potentially corrupted build cache

failed to load package %s: %w

Error message

failed to load package %s: %w

What it means

During the loading phase, a package (and its facts) could not be loaded from export data or source; golangci-lint wraps the cause with the package name. The error is not sent to the error channel directly because it is also recorded in package.Errors and surfaced by a higher layer, so users typically see the underlying cause wrapped at this level.

Source

Thrown at pkg/goanalysis/runner_loadingpackage.go:78

func (lp *loadingPackage) analyze(ctx context.Context, cancel context.CancelFunc, loadMode LoadMode, loadSem chan struct{}) {
	select {
	case <-ctx.Done():
		return
	case loadSem <- struct{}{}:
		defer func() {
			<-loadSem
		}()
	}

	// Save memory on unused more fields.
	defer lp.decUse(loadMode < LoadModeWholeProgram)

	if err := lp.loadWithFacts(loadMode); err != nil {
		// Note: this error is ignored when there is no facts loading (e.g. with 98% of linters).
		// But this is not a problem because the errors are added to the package.Errors.
		// You through an error, try to add it to actions, but there is no action annnddd it's gone!
		werr := fmt.Errorf("failed to load package %s: %w", lp.pkg.Name, err)

		// Don't need to write error to errCh, it will be extracted and reported on another layer.
		// Unblock depending on actions and propagate error.
		for _, act := range lp.actions {
			close(act.analysisDoneCh)

			act.Err = werr
		}

		if len(lp.actions) == 0 {
			lp.log.Warnf("no action but there is an error: %v", err)
		}

		return
	}

	actsWg, ctxGroup := errgroup.WithContext(ctx)

View on GitHub (pinned to ed7a235d2d)

Solutions

Run `go clean -cache` to clear a potentially corrupted build cache
Fix the root-cause package error reported alongside (see package.Errors output)
Re-run with a consistent Go toolchain version across the project
If persistent, disable fact-dependent linters or run without whole-program loading mode

Example fix

// shell
// before: golangci-lint run (stale cache)
// after
go clean -cache && golangci-lint run

Defensive patterns

Strategy: retry

Validate before calling

// clear stale build cache when load errors appear
exec.Command("go", "clean", "-cache").Run()

Try / catch

// retry once after cache cleanup on load failure
if strings.Contains(err.Error(), "failed to load package") {
    go clean -cache; retry lint once
}

Prevention

Use a consistent Go toolchain version (go.mod toolchain directive)
Avoid mutating build cache concurrently with lint runs
Fix root-cause package errors reported together with this error

When it happens

Trigger: loadWithFacts fails inside the loadingpackage goroutine (e.g. export data missing, ill-typed dependency) while analyzing with fact-dependent linters (whole-program or shared-facts loading modes).

Common situations: Stale or missing export data after switching Go versions; build cache corruption; dependency packages with compile errors in fact-loading modes; interrupted prior runs leaving partial cache.

Related errors

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