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

---
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. Asserted against Vale 3.15.2 by `tests/test-vale-3-15-2-behaviours.sh` (slug `house-vale-3-15-2-repro`) for the mapped column; the native-MDX column was observed with `mdx2vast` installed and is not covered by that test (it needs the binary):

| 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:
```markdown
<!-- vale off -->
This text will be ignored.
<!-- vale on -->
```

Native MDX only (no `[formats]` mapping, `mdx2vast` on `PATH`):
```mdx
{/* vale off */}
This text will be ignored.
{/* vale on */}
```

Org mode:
```org
# 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:
```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:
```mdx
{/* 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:

```yaml
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. Asserted against Vale 3.15.2 by the same test 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:

```yaml
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:

```yaml
      - 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

```bash
$ 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.