holocron/plugins/lint/skills/vale-run/references/troubleshooting.md

source_keys

source_keys
context7-websites-vale-sh house-vale-3-15-2-repro

Vale troubleshooting reference

Why a rule isn't applying

vale ls-config prints the fully-resolved, currently active configuration as JSON. Check that before rereading .vale.ini — what is written in the config file is not necessarily what is active, and the resolved output is the fastest way to see which config files, styles and StylesPath directories a run actually loaded.

It stops at styles. It does not enumerate rules, and neither does any other Vale 3.15.2 subcommand — ls-config, ls-dirs, ls-vars and ls-metrics were each checked and none names the rule. Against a config whose custom rule was demonstrably firing on the target file, ls-config reported "SBaseStyles": {"*.md": ["MyStyle"]} and the two StylesPath search paths, but "Checks": null, "SChecks": {"*.md": {}} and "RuleToLevel": {} — the firing rule's own name appeared nowhere in the output. So ls-config answers "is this style loaded, and from where", not "is this rule live". For the latter, run Vale over a small fixture that should trigger the rule and see whether it alerts.

Inline suppression syntax by format

Prerequisite: .mdx needs a decision before it lints at all

Vale 3.15.2 has no built-in MDX support. If .vale.ini does not map the extension, Vale takes the native MDX path and shells out to an external mdx2vast binary. Without it on PATH the run dies before linting anything:

$ vale .            # doc.md and doc.mdx both present, no [formats] mapping
E100 [lintMDX] Runtime error

mdx2vast not found

Execution stopped with code 1.
$ echo $?
2

That is the whole invocation, not just the .mdx file — the .md alongside it produced no output either. Fix it one of two ways, and the choice is not cosmetic because it also decides the suppression syntax:

.vale.ini	Prerequisite	Parser	Suppression form that works
[formats] maps mdx = md (what vale-config recommends)	none	Markdown	<!-- vale off -->
no mdx mapping (native MDX)	npm install -g mdx2vast	MDX	{/* vale off */}

Key the markup to that config row, never to the file extension. Verified against Vale 3.15.2, same three fixtures under each config:

File	Mapped mdx = md	Native MDX (mdx2vast installed)
no suppression (control)	alert, exit 1	alert, exit 1
<!-- vale off -->	suppressed, exit 0	E100 ... failed to parse MDX: Unexpected character `!`, exit 2
{/* vale off */}	not suppressed, exit 1	suppressed, exit 0

Under the mapping the JSX comment is worse than inert: it is linted as prose, so {/* vale Vale.Repetition = NO */} produced three alerts where the un-suppressed file produced one — its own markup tripped the rule twice more.

Markdown, and .mdx mapped onto it — HTML comments:

<!-- vale off -->
This text will be ignored.
<!-- vale on -->

Native MDX only (no [formats] mapping, mdx2vast on PATH):

{/* vale off */}
This text will be ignored.
{/* vale on */}

Org mode:

# vale off
This text will be ignored.
# vale on

Disabling a specific rule for specific matches

Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:

Markdown:

<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->
This is some text ACT test
<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->

Native MDX only — under [formats] mdx = md an .mdx file takes the Markdown form above, and this one silences nothing:

{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
This is some text ACT test
{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}

Ignoring words in spell check

The spelling check accepts an ignore list of external plain-text files, so project-specific terms don't need touching the dictionary:

extends: spelling
message: "Did you really mean '%s'?"
level: error
ignore:
  - ignore1.txt
  - ignore2.txt

Where the file goes, and why a wrong answer is invisible. Each entry resolves against the StylesPath root, or against the working directory vale is invoked from. It does not resolve against the rule file's own directory — which is the natural reading of the YAML above, since the path sits inside the rule, and it is wrong. Verified against Vale 3.15.2 across four fresh trees, each with the same rule and the same unknown word:

Where ignore1.txt was placed	Result
<StylesPath>/ignore1.txt	word ignored, exit 0
./ignore1.txt in the directory vale runs from	word ignored, exit 0
<StylesPath>/<Style>/ignore1.txt, beside the rule	word still flagged, exit 1
file absent entirely	word still flagged, exit 1

The two failing rows emit no warning, no error, and no diagnostic of any kind: the output is byte-identical to the same rule with the ignore key deleted. A misplaced ignore list looks exactly like a list that was read and did not contain the word.

Prefer the StylesPath root. The run-directory form is the fragile one — move the invocation and it silently stops working. Same tree, same file, only the working directory changed:

$ cd project && vale doc.md                                  # ignore1.txt at project root
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.          # exit 0

$ cd /elsewhere && vale --config=project/.vale.ini project/doc.md
 1:5  error  Did you really mean 'zzqwidget'?  MyStyle.Spell  # exit 1

The StylesPath copy survives that move; the run-directory copy does not.

Plain-text fallback

If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with --ignore-syntax to treat it as plain text instead of relying on the format-specific parser.

CI failing unexpectedly

Only error-level alerts make Vale exit non-zero; warning and suggestion alerts are printed but exit 0. If a CI job fails solely because of error-level alerts — not because the content is actually wrong for that pipeline stage — add --no-exit rather than suppressing the rule itself. This preserves the lint output while not gating the build on it. If the alerts are warnings or suggestions, Vale did not fail the job — look elsewhere.

pre-commit integration

Vale ships a pre-commit hook definition. A typical setup runs vale sync once (with pass_filenames: false) plus the actual lint pass with CI-appropriate flags:

repos:
  - repo: https://github.com/errata-ai/vale
    rev: 16d3a7f
    hooks:
      - id: vale
        name: vale sync
        pass_filenames: false
        args: [sync]
      - id: vale
        args: [--output=line, --minAlertLevel=error]

If the project has documented a wrapper script for a known Vale scope/escaping limitation (see the Gotchas section of SKILL.md), point the second hook's entry: at that wrapper instead of at bare vale, even though the hook's repo/rev/id still come from the upstream definition above — only the invocation target changes:

      - id: vale
        entry: <path-to-project-wrapper>
        args: [--output=line, --minAlertLevel=error]

Using the upstream hook's bare vale entry in a project that has such a wrapper reintroduces exactly the bug the wrapper exists to fix.

CI output for machine parsing

$ vale --output=JSON README.md

Use --output=JSON when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.