golangci/golangci-lint · error

unable to load custom analyzer %q: %s, %w

Error message

unable to load custom analyzer %q: %s, %w

What it means

Wrapping error in PluginGoBuilder.Build: loading a Go plugin (.so) custom linter failed inside loadConfig — the plugin file could not be opened, the base path could not be resolved, or the plugin's symbols did not match the expected interfaces. The linter name, its configured path, and the root cause are embedded.

Source

Thrown at pkg/lint/lintersdb/builder_plugin_go.go:50

	return &PluginGoBuilder{log: log}
}

// Build loads custom linters that are specified in the golangci-lint config file.
func (b *PluginGoBuilder) Build(cfg *config.Config) ([]*linter.Config, error) {
	if cfg == nil || b.log == nil {
		return nil, nil
	}

	var linters []*linter.Config

	for name, settings := range cfg.Linters.Settings.Custom {
		if settings.Type != goPluginType && settings.Type != "" {
			continue
		}

		lc, err := b.loadConfig(cfg, name, &settings)
		if err != nil {
			return nil, fmt.Errorf("unable to load custom analyzer %q: %s, %w", name, settings.Path, err)
		}
		linters = append(linters, lc)
	}

	return linters, nil
}

// loadConfig loads the configuration of private linters.
// Private linters are dynamically loaded from .so plugin files.
func (b *PluginGoBuilder) loadConfig(cfg *config.Config, name string, settings *config.CustomLinterSettings) (*linter.Config, error) {
	analyzers, err := b.getAnalyzerPlugin(cfg, settings.Path, settings.Settings)
	if err != nil {
		return nil, err
	}

	b.log.Infof("Loaded %s: %s", settings.Path, name)

	customLinter := goanalysis.NewLinter(name, settings.Description, analyzers, nil).

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Verify the plugin .so file exists at the configured path and was built with the same toolchain/OS/arch
2. Rebuild the plugin against the same Go version and golangci-lint version used at runtime
3. Check the wrapped error for whether Open, path resolution, or symbol lookup failed
4. On Windows, note plugin.Open is unsupported

When it happens

Trigger: Thrown at pkg/lint/lintersdb/builder_plugin_go.go:50 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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