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

# Vale troubleshooting reference

## Inline suppression syntax by format

Markdown/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:

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

If a CI job fails solely because Vale returns a non-zero exit code on found 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.

## 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]
```

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