golangci/golangci-lint · error

process extra words: %w

Error message

process extra words: %w

What it means

When configuring misspell, golangci-lint merges user-supplied extra words (typo/correction pairs) into the replacer via appendExtraWords. If that helper fails — empty typo/correction fields or non-letter characters — the error is wrapped as "process extra words" and the linter constructor fails.

Source

Thrown at pkg/golinters/misspell/misspell.go:63

	replacer := &misspell.Replacer{
		Replacements: misspell.DictMain,
	}

	// Figure out regional variations
	switch strings.ToUpper(settings.Locale) {
	case "":
		// nothing
	case "US":
		replacer.AddRuleList(misspell.DictAmerican)
	case "UK", "GB":
		replacer.AddRuleList(misspell.DictBritish)
	case "NZ", "AU", "CA":
		return nil, fmt.Errorf("unknown locale: %q", settings.Locale)
	}

	err := appendExtraWords(replacer, settings.ExtraWords)
	if err != nil {
		return nil, fmt.Errorf("process extra words: %w", err)
	}

	if len(settings.IgnoreRules) != 0 {
		replacer.RemoveRule(settings.IgnoreRules)
	}

	// It can panic.
	replacer.Compile()

	return replacer, nil
}

func runMisspellOnFile(pass *analysis.Pass, file *ast.File, replacer *misspell.Replacer, mode string) error {
	position, isGoFile := goanalysis.GetGoFilePosition(pass, file)
	if !isGoFile {
		return nil
	}

View on GitHub (pinned to ed7a235d2d)

Solutions

1. Inspect each extra-words entry: both typo and correction must be non-empty.
2. Remove non-letter characters (spaces, digits, hyphens, apostrophes) from typo and correction values.
3. Split multi-word phrases into single words or use a different mechanism; each field must be a single alphabetic word.
4. Validate your config with `golangci-lint config verify` before running the linter.

Example fix

# before
linters-settings:
  misspell:
    extra-words:
      - typo: ""
        correction: "cannot"
# after
linters-settings:
  misspell:
    extra-words:
      - typo: "cant"
        correction: "cannot"

for _, w := range cfg.Misspell.ExtraWords {
    if w.Typo == "" || w.Correction == "" {
        return errors.New("extra-words entries need non-empty typo and correction")
    }
}

When it happens

Trigger: A linters-settings.misspell.extra-words entry has an empty typo or correction, or contains non-letter characters (spaces, digits, punctuation, hyphens), causing appendExtraWords to return an error which runMisspell's setup wraps.

Common situations: Custom extra-words lists with blank YAML keys, copy-pasted entries with trailing spaces, or users trying to add multi-word phrases like "cant -> cannot wait" which contain a space.

Related errors

• unknown locale: %q
• can't get file %s contents: %w
• typo (%q) and correction (%q) fields should not be empty
• the word %q in the 'typo' field should only contain letters
• the word %q in the 'correction' field should only contain le

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