---
source_keys:
  - context7-websites-vale-sh
---

# 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 styles and rules a run actually
loaded.

## Inline suppression syntax by format

Markdown uses HTML comments — the MDX `{/* */}` form does not suppress anything in a plain `.md` file:
```markdown
<!-- vale off -->
This text will be ignored.
<!-- vale on -->
```

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

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

## 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.