golangci/golangci-lint · error

constructing mapstructure decoder: %w

Error message

constructing mapstructure decoder: %w

What it means

Load wraps the error from mapstructure.NewDecoder when the decoder with the library's DecodeHookFunc and WeaklyTypedInput options cannot be constructed. This almost only fails if the provided DecodeHookFunc itself is invalid, so it signals an internal configuration-decoding setup problem in the migrate tooling rather than a user config problem.

Source

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

	defer func() { _ = file.Close() }()

	raw := map[string]any{}

	err = parser.Decode(file, raw)
	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. Upgrade to the latest golangci-lint release; this indicates an internal bug.
2. Check the golangci-lint issue tracker for known 'constructing mapstructure decoder' reports.
3. If using a custom build, verify config.DecodeHookFunc() returns a valid mapstructure.DecodeHookFunc.
4. Report a bug with the full error chain and version (golangci-lint version) if it persists.

if err := fakeloader.Load(srcPath, &old); err != nil {
    if strings.Contains(err.Error(), "constructing mapstructure decoder") {
        // internal bug: upgrade golangci-lint or report issue
    }
    return err
}

When it happens

Trigger: config.DecodeHookFunc() returns an invalid hook composition (e.g. a nil hook or malformed DecodeHook chain) passed into mapstructure.DecoderConfig, causing NewDecoder validation to fail.

Common situations: Encountered after upgrading golangci-lint or its config dependency where the decode hook setup changed; custom builds with a patched config package; effectively never caused by the user's YAML/TOML file.

Related errors

• decoding configuration file: %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/d818c8b89dc9c1d7. Report an issue: GitHub.