golangci/golangci-lint · error

no plugins defined

Error message

no plugins defined

What it means

`Configuration.Validate` (pkg/commands/internal/configuration.go:43) rejects a `.custom-gcl.*` config whose `plugins` list is empty or missing. The whole purpose of the custom golangci-lint builder is to compile one or more plugin modules into the binary, so a config without plugins is meaningless and validation stops here. Note the check is `len(c.Plugins) == 0`, so an empty list `plugins: []` also triggers it.

Source

Thrown at pkg/commands/internal/configuration.go:43

	// Destination is the path to a directory to store the binary.
	Destination string `yaml:"destination,omitempty"`

	// Plugins information.
	Plugins []*Plugin `yaml:"plugins,omitempty"`
}

// Validate checks and clean the configuration.
func (c *Configuration) Validate() error {
	if strings.TrimSpace(c.Version) == "" {
		return errors.New("root field 'version' is required")
	}

	if strings.TrimSpace(c.Name) == "" {
		c.Name = defaultBinaryName
	}

	if len(c.Plugins) == 0 {
		return errors.New("no plugins defined")
	}

	for _, plugin := range c.Plugins {
		if strings.TrimSpace(plugin.Module) == "" {
			return errors.New("field 'module' is required")
		}

		if strings.TrimSpace(plugin.Import) == "" {
			plugin.Import = plugin.Module
		}

		if strings.TrimSpace(plugin.Path) == "" && strings.TrimSpace(plugin.Version) == "" {
			return errors.New("missing information: 'version' or 'path' should be provided")
		}

		if strings.TrimSpace(plugin.Path) != "" && strings.TrimSpace(plugin.Version) != "" {
			return errors.New("invalid configuration: 'version' and 'path' should not be provided at the same time")
		}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Add at least one entry under the root `plugins` key of the .custom-gcl config
2. Verify indentation so `plugins` is a root-level list, not nested or misnamed (e.g. `plugin:`)
3. If no plugins are actually needed, build the standard golangci-lint binary instead of using custom-gcl

Example fix

# before (.custom-gcl.yml)
version: v2.1.6
# after
version: v2.1.6
plugins:
  - module: github.com/me/my-plugin
    version: v1.0.0

data, _ := os.ReadFile(".custom-gcl.yml")
var raw struct {
	Plugins []map[string]any `yaml:"plugins"`
}
_ = yaml.Unmarshal(data, &raw)
if len(raw.Plugins) == 0 {
	// add at least one plugin before running the build
}

When it happens

Trigger: Validating a `.custom-gcl.yml` that has `version` set but no `plugins` key, an empty `plugins:` key (decodes to nil), or an explicitly empty list `plugins: []`.

Common situations: Scaffolding the config file before adding plugins and running the build too early; commenting out all plugin entries; a YAML indentation mistake that puts plugins under another key so the root list stays empty.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• root field 'version' is required
• field 'module' is required
• missing information: 'version' or 'path' should be provided
• invalid configuration: 'version' and 'path' should not be pr
• the configuration contains invalid elements

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