golangci/golangci-lint · error

decoding configuration file: %w

Error message

decoding configuration file: %w

What it means

Load wraps errors from decoder.Decode(raw), which converts the parsed raw map into the configuration struct. Because the fakeloader exists to preserve original key casing for linter configuration, this fires when the configuration file's content does not match the expected configuration schema or types.

Source

Thrown at pkg/commands/internal/migrate/fakeloader/fakeloader.go:44

	if err != nil {
		return err
	}

	// NOTE: this is inspired by viper internals.
	cc := &mapstructure.DecoderConfig{
		Result:           old,
		WeaklyTypedInput: true,
		DecodeHook:       config.DecodeHookFunc(),
	}

	decoder, err := mapstructure.NewDecoder(cc)
	if err != nil {
		return fmt.Errorf("constructing mapstructure decoder: %w", err)
	}

	err = decoder.Decode(raw)
	if err != nil {
		return fmt.Errorf("decoding configuration file: %w", err)
	}

	return nil
}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Read the wrapped message: it names the offending key/type — fix that field in the config file.
2. Run `golangci-lint migrate` or `golangci-lint config verify` against a JSON-schema-validated editor setup.
3. Remove or update deprecated settings from older golangci-lint versions before migrating.
4. Test with a minimal config and re-add sections until the failing key is isolated.

Example fix

// before (.golangci.yml)
linters:
  enable: gocritic
// after
linters:
  enable:
    - gocritic

// validate config against the golangci-lint JSON schema before loading
// golangci-lint config verify
// or in CI:
//   curl -sSf https://golangci-lint.run/ schema.json && ajv validate -s schema.json .golangci.yml

if err := fakeloader.Load(srcPath, &old); err != nil {
    var derr *mapstructure.Error
    if errors.As(err, &derr) {
        for _, e := range derr.Errors { log.Printf("bad config key: %s", e) }
    }
    return err
}

When it happens

Trigger: decoder.Decode(raw) fails: wrong value types (string where int expected), unknown/mistyped keys rejected by the hook, or a structurally invalid config map produced by an earlier parse step.

Common situations: A .golangci.yml with malformed settings, values of the wrong type (e.g. `linters: true` instead of a mapping), leftover keys from an older golangci-lint version, or hand-edited config typos.

Related errors

• constructing mapstructure decoder: %w
• hash plugin directory: %w
• file %s not found: %w
• file %s open: %w
• YAML decoding: %w

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