cspell error: unknown words found in PR, how to fix dictionary

TL;DR

Add the legitimate words to the project dictionary instead of touching the code. Put them in the words array in cspell.json (or a shared dictionary file) so every future PR gets them for free. Re-run cspell and confirm a clean exit before pushing.

Verbatim error

cspell error: unknown words found in PR, how to fix dictionary

Steps

1. Run cspell on the flagged files: cspell --no-progress docs/guide.md src/review.ts (your real paths).

Expected: output lists each unknown word with its file and line, like Unknown word (foobar).

1. Sort the flagged words into real typos and legitimate terms. Fix the real typos in the source files.

Expected: only product names, technical jargon, and identifiers remain flagged.

1. Add the legitimate words to cspell.json at the repo root:

   {
     "words": ["foobar", "reviewdog", "golangci"]
   }

Expected: re-running cspell on the same files reports no issues and exits 0.

1. For words shared across repos, put them in a dictionary text file (one word per line) and reference it from cspell.json under dictionaryDefinitions, so teams share one list.

Expected: new repos get the shared words by importing the config, not by copy-pasting word lists.

Use this when

• cspell flags correct technical terms or product names in a PR.
• You need to add words to the cspell project dictionary.
• An agent's PR fails spell check on identifiers the agent invented correctly.

Not for this skill when

• The flagged words are actual typos (fix the spelling, do not add typos to the dictionary).
• cspell crashes or cannot find its config (check the config path and JSON syntax first).
• You want spell checking for a language cspell does not cover (that needs a different tool).

Variant phrasings

• cspell unknown words how to add to dictionary
• cspell fails PR on technical terms
• cspell.json words list not working

Why it happens

cspell ships with general-language dictionaries, so any domain term, product name, or code identifier looks like a misspelling to it. The project dictionary is the intended escape hatch, but teams often never populate it, so every PR rediscovers the same false positives. A curated word list turns the gate from noisy to useful.

Edge cases

• Case sensitivity: adding foobar also covers Foobar in most configs, but all-caps acronyms sometimes need their own entry. Check with cspell trace WORD to see how a word resolves.
• Compound identifiers like reviewBot get split into review and bot; if a fragment is flagged, add the fragment, not the compound.
• Generated files and lockfiles should be in ignorePaths, not in the dictionary. Do not add minified bundle tokens as words.
• Words with digits (like utf8) are usually fine, but version strings in docs churn; prefer ignoring generated changelogs over dictionarying every version token.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstk3b6JG3E26vkjj_oOXgIA