golangci/golangci-lint · error

the configuration contains invalid elements

Error message

the configuration contains invalid elements

What it means

This error is returned by `config verify` (`executeVerify` in pkg/commands/config_verify.go:39) when the golangci-lint configuration file fails JSON Schema validation. The linter parses the config, validates it against the bundled JSON Schema for the current golangci-lint version, prints each schema violation via `printValidationDetail`, and then returns this generic sentinel message. It means the file exists and is parseable YAML/JSON/TOML, but its content contains keys, values, or structures the schema does not allow.

Source

Thrown at pkg/commands/config_verify.go:39

func (c *configCommand) executeVerify(cmd *cobra.Command, _ []string) error {
	usedConfigFile := c.getUsedConfig()
	if usedConfigFile == "" {
		c.log.Warnf("No config file detected")
		os.Exit(exitcodes.NoConfigFileDetected)
	}

	c.log.Infof("Verifying the configuration file %q with the JSON Schema", usedConfigFile)

	err := validateConfiguration(jsonsch.NextSchema, usedConfigFile)
	if err != nil {
		var v *jsonschema.ValidationError
		if !errors.As(err, &v) {
			return fmt.Errorf("[%s] validate: %w", usedConfigFile, err)
		}

		printValidationDetail(cmd, v.DetailedOutput())

		return errors.New("the configuration contains invalid elements")
	}

	return nil
}

func validateConfiguration(schemaPath, targetFile string) error {
	compiler := jsonschema.NewCompiler()
	compiler.UseLoader(jsonsch.NewEmbedLoader())
	compiler.DefaultDraft(jsonschema.Draft7)

	// The name is not us
	schema, err := compiler.Compile(schemaPath)
	if err != nil {
		return fmt.Errorf("compile schema: %w", err)
	}

	var m any

View on GitHub (pinned to ed7a235d2d)

Solutions

  1. Run `golangci-lint config verify` and read each printed `jsonschema: ...` line above this error — it names the exact dotted path and keyword that failed
  2. Fix the reported keys/values in the configuration file (remove unknown options, correct types/enums)
  3. Regenerate or consult the schema for your version (`golangci-lint config` docs / jsonschema output) to confirm valid option names
  4. If the config was migrated from v1, run the v2 migration and re-verify

Example fix

# before (.golangci.yml)
linters:
  enable: gocritic
  fast: true
# after
linters:
  enable:
    - gocritic
settings:
  gocritic:
    enabled-checks:
      - rangeValCopy
Defensive patterns

Strategy: validation

Validate before calling

# shell — validate before other tooling consumes the config
if ! golangci-lint config verify; then
  echo ".golangci.yml is invalid; fix reported jsonschema errors first" >&2
  exit 1
fi

Try / catch

err := cmd.Run()
var vErr *exitcodes.ExitError
if err != nil && strings.Contains(err.Error(), "the configuration contains invalid elements") {
    // read the printed jsonschema detail lines and fix the config
}
_ = vErr

Prevention

When it happens

Trigger: Running `golangci-lint config verify` (or any command whose preRunE validates config) against a configuration file that decodes successfully but violates the golangci-lint JSON Schema: unknown top-level keys, wrong option types (e.g. `linters: enable` given a string instead of a list), invalid enum values, or options that do not exist in the schema version being used.

Common situations: Copying config snippets from blog posts or other projects with typos or deprecated keys; upgrading or downgrading golangci-lint so previously valid options disappear from the schema; mixing v1 and v2 configuration layouts; hand-editing YAML and mis-nesting keys.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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