# How to Diagnose Failed Suppressions Using the react-doctor --explain Flag

> Learn how the react-doctor --explain flag diagnoses failed suppressions. Uncover why rules fire and suppressions fail on specific lines with this powerful diagnostic tool.

- Repository: [Million Software, Inc./react-doctor](https://github.com/millionco/react-doctor)
- Tags: how-to-guide
- Published: 2026-05-12

---

**The `--explain` flag (alias `--why`) runs a targeted, silent diagnostic scan that reveals exactly why a specific rule fired and why a suppression comment failed to silence it at a given line.**

The `react-doctor` CLI includes a specialized diagnostic mode designed to debug false positives and misconfigured inline suppressions. When a `// react-doctor-disable-next-line` comment fails to suppress a rule, the `--explain` flag provides a focused, line-level analysis of the mismatch between the diagnostic and the suppression directive.

## How the --explain Flag Works

The diagnostic flow implemented in [`packages/react-doctor/src/cli.ts`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/cli.ts) follows a strict pipeline to isolate and explain specific rule violations.

### Target Selection and Project Resolution

The `runExplain()` function, located at lines 274–382 of [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts), requires a `<file>:<line>` argument (e.g., `src/App.tsx:42`). It parses this input and calls `resolveExplainTargetDirectory()` to identify the owning project context. If the `--project` flag is provided, it restricts the search to that specific project; otherwise, it resolves the project from the file path.

### Silent Diagnostic Scanning

Once the target is resolved, `runExplain()` triggers a full project scan with **silent mode** enabled. According to lines 78–84 of [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts), the scan executes with `silent: true` and `offline: true`, ensuring that only raw diagnostic objects are collected without UI formatting, progress bars, or network-dependent features.

### Line-Level Filtering and Suppression Analysis

The scan results are filtered to diagnostics matching the exact `filePath` and `line` provided by the user (lines 86–90 of [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts)). For each matching diagnostic, the system checks for a `suppressionHint` property. This hint is injected by `filterInlineSuppressions()` in [`src/utils/filter-diagnostics.ts`](https://github.com/millionco/react-doctor/blob/main/src/utils/filter-diagnostics.ts) (lines 61–66) when a rule is not suppressed but a nearby disable comment exists with a mismatching rule name or malformed syntax.

## Understanding Suppression Hints

The **suppression hint** mechanism diagnoses "near misses" between suppression comments and actual diagnostics. When `filterInlineSuppressions()` detects a `// react-doctor-disable-next-line` comment that is either missing, malformed, or targeting a different rule, it generates a detailed explanation.

For example, if a disable comment on line 41 targets `no-inline-styles` but the diagnostic on line 42 is for `react-hooks-exhaustive-deps`, the hint explains: *"disable comment found on line 41 applies to rule 'no-inline-styles', but the diagnostic is for 'react-hooks-exhaustive-deps'."* This precision eliminates guesswork when suppression comments fail silently.

## Usage Examples

Invoke the diagnostic mode using either the `--explain` or `--why` alias followed by a file path and line number separated by a colon.

```bash

# Diagnose a specific line

npx react-doctor --explain src/App.tsx:42

# Using the alias

npx react-doctor --why src/App.tsx:42

```

When a suppression hint exists, the output identifies the specific mismatch:

```text
✗ react-hooks/exhaustive-deps (⚠) — React hook has missing dependency
  Suppression diagnosis: disable comment on line 41 applies to rule 'no-inline-styles', not 'exhaustive-deps'

```

If no suppression comment is detected, the output prompts for remediation:

```text
⚠ react-hooks/exhaustive-deps (⚠) — React hook has missing dependency
  No nearby react-doctor-disable-next-line comment was detected — add one immediately above this line to suppress.

```

## Constraints and Isolation Mode

The `--explain` flag operates in **strict isolation**. As enforced by lines 66–73 of [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts), it cannot be combined with other output modes such as `--json`, `--score`, `--annotations`, or `--staged`. This constraint ensures the explanation remains the sole output, preventing conflicting formatting or data structures from obscuring the diagnostic details.

## Summary

- The `--explain` (or `--why`) flag performs a silent, offline scan targeting a specific `file:line` coordinate.
- It filters diagnostics to the exact location and checks for `suppressionHint` properties added by `filterInlineSuppressions()`.
- **Suppression hints** reveal why a `// react-doctor-disable-next-line` comment failed, detailing rule mismatches or malformed syntax.
- The mode cannot be combined with `--json`, `--score`, or other output flags, ensuring focused, readable diagnostic output.
- If no suppression comment is found, the tool explicitly advises adding one above the flagged line.

## Frequently Asked Questions

### What is the difference between `--explain` and `--why`?

There is no functional difference; `--why` is simply an alias for `--explain`. Both invoke the `runExplain()` function in [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts) and accept a `<file>:<line>` argument to diagnose specific rule violations and failed suppressions.

### Why does `--explain` require a `file:line` argument?

The flag requires precise coordinates to filter the diagnostic stream effectively. According to the implementation in [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts) lines 86–90, the tool matches diagnostics by exact `filePath` and `line` number, allowing it to isolate the specific suppression logic and generate targeted hints without processing unrelated violations.

### Can I use `--explain` with `--json` output?

No. The `runExplain()` function explicitly forbids combining `--explain` with `--json`, `--score`, `--annotations`, or `--staged` flags (lines 66–73 of [`cli.ts`](https://github.com/millionco/react-doctor/blob/main/cli.ts)). This design ensures that explanatory text and suppression diagnoses remain human-readable and are not corrupted by structured data formatting.

### What does it mean when no suppression hint is shown?

If the output displays a diagnostic but states *"No nearby react-doctor-disable-next-line comment was detected"*, it indicates that `filterInlineSuppressions()` found no suppression comments in the vicinity of the flagged line. The tool is prompting you to add a properly formatted `// react-doctor-disable-next-line <rule-name>` comment immediately above the diagnostic line to suppress the warning.