cspell "Unknown word (X)" spelling failure in CI

By Kaveh Alemi·Latchkey

cspell checked your files and found tokens not in any active dictionary, reporting each as "Unknown word (X)" and exiting non-zero. Domain terms, product names, and identifiers commonly trip it.

What this error means

cspell prints lines like "Unknown word (kubectl)" with the file, line, and column, and ends with "Issues found: N in M files", failing the job.

docs/guide.md:12:8 - Unknown word (kubectl)
docs/guide.md:40:3 - Unknown word (Latchkey)
CSpell: Files checked: 42, Issues found: 2 in 1 files.

Common causes

Project vocabulary is not in a dictionary

Commands, brand names, and abbreviations are not in cspell built-in dictionaries, so each is an unknown word.

No custom words list or dictionary is configured

Without a words array or a custom dictionary file in cspell.json, every unrecognized token fails the check.

How to fix it

Add terms to cspell.json words or a dictionary file

1. Add short-lived terms to the words array in cspell.json.
2. For larger lists, reference a custom dictionary file.
3. Commit the config so CI recognizes the vocabulary.

{
  "version": "0.2",
  "words": ["kubectl", "Latchkey", "OAuth"],
  "dictionaryDefinitions": [
    { "name": "project", "path": "./project-words.txt", "addWords": true }
  ],
  "dictionaries": ["project"]
}

Ignore paths that should not be spell-checked

Exclude generated files and code samples from cspell so they do not produce noise.

{
  "ignorePaths": ["CHANGELOG.md", "**/node_modules/**", "dist/**"]
}

How to prevent it

• Keep a committed project-words.txt dictionary and grow it with new terms.
• Use ignorePaths for generated content and vendored files.
• Run cspell in pre-commit so unknown words are caught before CI.

Frequently asked questions

Related guides

References

• GitHub Actions documentation