golangci/golangci-lint · error

root field 'version' is required

Error message

root field 'version' is required

What it means

`Configuration.Validate` (pkg/commands/internal/configuration.go:35) requires the root `version` field of a `.custom-gcl.*` (custom golangci-lint builder) configuration to be a non-blank string. This field pins which golangci-lint release the custom binary is built from; without it the builder cannot resolve a base version, so validation fails immediately. Empty/whitespace-only values are rejected via `strings.TrimSpace`.

Source

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

// Configuration represents the configuration file.
type Configuration struct {
	// golangci-lint version.
	Version string `yaml:"version"`

	// Name of the binary.
	Name string `yaml:"name,omitempty"`

	// 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
		}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Add a `version` field at the root of the .custom-gcl config file pinning a golangci-lint release, e.g. `version: v2.1.6`
2. Check for YAML key typos/indentation so the value actually lands in the `version` field
3. Re-create the config from the custom-gcl documentation template, then fill in your plugins

Example fix

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

cfg, err := yaml.Marshal(map[string]any{
	"version": "v2.1.6",
	"plugins": []any{
		map[string]any{"module": "github.com/me/my-plugin", "version": "v1.0.0"},
	},
})
_ = os.WriteFile(".custom-gcl.yml", cfg, 0o644)

When it happens

Trigger: Loading and validating a `.custom-gcl.yml` (or .yaml/.json) file whose top-level `version:` key is absent, empty (`version: ""`), or whitespace only, before running the custom binary build.

Common situations: Creating a fresh plugin config with only the `plugins` section; deleting the version line during refactoring; a template that left `version:` with no value; YAML key typo like `versions:` or `Version:` that silently decodes as 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

• no plugins defined
• 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/b721de8082abbab5. Report an issue: GitHub.