Troubleshooting - React Doctor

Solutions to common problems when using React Doctor.

Node.js Version Issues

React Doctor requires specific Node.js versions for lint checks.

Required Version

Oxlint (the linter used by React Doctor) requires:

Node.js ^20.19.0 or >=22.12.0

Check your version:

node --version

Unsupported Node.js Version

If you see:

Node v18.0.0 is not compatible with oxlint (requires ^20.19.0 || >=22.12.0).
Lint checks will be skipped.

You have three options:

Option 1: Upgrade Node.js

# Using nvm
nvm install 24
nvm use 24

# Using n
n latest

# Using official installer
# Download from https://nodejs.org

Option 2: Install via nvm (Recommended)

React Doctor can install a compatible Node.js version automatically:

npx react-doctor .
# Prompts: "Install Node 24 via nvm to enable lint checks?"

Or manually:

nvm install 24
npx react-doctor .

React Doctor will use Node 24 from nvm for lint checks while keeping your system Node.js version unchanged.

Option 3: Use npx with Matching Node

npx -p oxlint@latest react-doctor@latest .

This bundles oxlint with native bindings for your Node version.

nvm Not Installed

If you don’t have nvm:

# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then:
nvm install 24

Windows users: Use nvm-windows

Native Binding Error

If you see:

Lint checks failed — oxlint native binding not found (Node v18.0.0).

This means oxlint can’t find prebuilt binaries for your Node version. Solution:

npx -p oxlint@latest react-doctor@latest .

Or upgrade Node.js to v24 (recommended).

React Doctor will skip lint checks if Node.js is incompatible. You’ll only get dead code detection results.

Performance Issues

React Doctor can be slow on large codebases.

Scan Takes Too Long

Use Diff Mode

Scan only changed files:

npx react-doctor . --diff

This is 10-100× faster than full scans.

Select Specific Project

In monorepos, scan one project:

npx react-doctor . --project web

Disable Dead Code Detection

Dead code analysis is slow on large projects:

npx react-doctor . --no-dead-code

Or in config:

react-doctor.config.json

{
  "deadCode": false
}

Ignore Generated Files

Exclude large generated directories:

react-doctor.config.json

{
  "ignore": {
    "files": [
      "**/dist/**",
      "**/build/**",
      "**/.next/**",
      "**/node_modules/**",
      "**/*.generated.ts"
    ]
  }
}

Combine strategies for maximum speed: npx react-doctor . --project web --diff --no-dead-code

Knip Hangs or Times Out

Dead code detection (via Knip) can stall on complex projects. Solution 1: Increase timeout in Knip config Create knip.json:

knip.json

{
  "$schema": "https://unpkg.com/knip@5/schema.json",
  "ignore": ["dist/**", "build/**"]
}

Solution 2: Disable dead code detection

npx react-doctor . --no-dead-code

Solution 3: Use diff mode (skips dead code automatically)

npx react-doctor . --diff

Installation Issues

npx Command Not Found

npx comes with npm. Ensure Node.js is installed:

node --version
npm --version

If not installed, download from nodejs.org.

Permission Denied

On macOS/Linux:

sudo npx -y react-doctor@latest .

Or fix npm permissions: docs.npmjs.com/resolving-eacces-permissions-errors

Slow Installation

React Doctor downloads dependencies on first run. Use -y to auto-accept:

npx -y react-doctor@latest .

Score Calculation Issues

Score Not Calculated

If you see:

You are offline, could not calculate score. Reconnect to calculate.

Causes:

No internet connection - React Doctor requires API access to calculate scores
Firewall blocking - Corporate firewalls may block react.doctor API
Using —offline flag - You explicitly disabled telemetry

Solutions:

Connect to the internet
Check firewall settings
Remove --offline flag

React Doctor sends diagnostics (anonymized) to calculate accurate scores. No source code is transmitted.

Score Seems Wrong

Scores are based on unique rule violations, not total occurrences. Example:

100 diagnostics from 5 unique rules = Score ~92
10 diagnostics from 10 unique rules = Score ~85

See Understanding Scores for details.

Score Doesn’t Improve After Fixes

If the score stays the same after fixes:

Verify fixes applied - Run with --verbose to see remaining issues
Check suppressed rules - Suppressed rules still count toward total
New issues introduced - Fixes may have created new violations

Re-run with verbose output:

npx react-doctor . --verbose

Configuration Issues

Config Not Loaded

React Doctor looks for:

react-doctor.config.json in project root
reactDoctor key in package.json

Verify config location:

# Should be at project root
ls react-doctor.config.json

Test config:

npx react-doctor .
# Should output: "Loaded react-doctor config."

Invalid Config Format

Config must be valid JSON:

react-doctor.config.json

{
  "ignore": {
    "rules": ["react/no-danger"],
    "files": ["src/generated/**"]
  }
}

Validate JSON syntax: jsonlint.com

Rules Still Appearing After Suppression

Ensure rule names match exactly:

{
  "ignore": {
    "rules": [
      "react/no-danger",     // ✓ Correct
      "react-hooks/rules-of-hooks",  // ✓ Correct
      "knip/exports"         // ✓ Correct
    ]
  }
}

Run with --verbose to see exact rule names:

npx react-doctor . --verbose
# Shows: plugin/rule format (e.g., react/no-danger)

Git and Diff Mode Issues

”Not a git repository”

Diff mode requires Git:

git init
git add .
git commit -m "Initial commit"

No Changed Files Detected

If React Doctor says no changes:

Commit your changes - Git only detects committed changes
Specify base branch - npx react-doctor . --diff main
Check file types - Only .ts, .tsx, .js, .jsx are scanned

List changed files:

git diff --name-only main...HEAD

Base Branch Not Found

React Doctor looks for main then master. If neither exists:

npx react-doctor . --diff develop

Or create the base branch:

git checkout -b main

CI/CD Issues

GitHub Actions: fetch-depth Error

Diff mode needs Git history:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0  # Required!

CI Hangs or Times Out

Large codebases can exceed CI time limits: Solution 1: Use diff mode

- uses: millionco/react-doctor@main
  with:
    diff: main

Solution 2: Disable dead code detection

- uses: millionco/react-doctor@main
  with:
    dead-code: false

Solution 3: Increase timeout

jobs:
  scan:
    timeout-minutes: 30

CI Fails with Exit Code 1

If you’re using --fail-on flag:

npx react-doctor . --fail-on error

React Doctor exits with code 1 when errors are found. This is expected behavior. To ignore in CI:

- run: npx react-doctor . || true

Or remove --fail-on flag.

Monorepo Issues

Workspaces Not Detected

React Doctor requires workspace config: npm/Yarn/pnpm:

package.json

{
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

pnpm:

pnpm-workspace.yaml

packages:
  - 'packages/*'
  - 'apps/*'

Verify workspaces:

npm list --depth=0
# or
pnpm list -r --depth=0

Project Not Found

If --project fails:

# List projects interactively
npx react-doctor .

Use the exact name shown in the prompt.

Scanning Takes Too Long in Monorepo

Scan specific projects:

npx react-doctor . --project web --diff

See Monorepo Projects for optimization tips.

Output and Display Issues

Colors Not Showing

Terminals without color support:

export FORCE_COLOR=1
npx react-doctor .

Or disable colors:

export NO_COLOR=1
npx react-doctor .

Verbose Output Truncated

Full diagnostics are written to temp directory:

npx react-doctor .
# Outputs: Full diagnostics written to /tmp/react-doctor-xxx

Read specific rules:

cat /tmp/react-doctor-xxx/react--no-danger.txt

JSON Output

For programmatic use:

import { diagnose } from "react-doctor/api";

const result = await diagnose(".");
console.log(JSON.stringify(result, null, 2));

Coding Agent Integration Issues

Skill Not Recognized

Re-install the skill:

curl -fsSL https://react.doctor/install-skill.sh | bash

Verify installation:

ls ~/.opencode/skills/react-doctor
ls ~/.cursor/skills/react-doctor

Agent Doesn’t Run Automatically

Coding agents run React Doctor when:

You explicitly ask (“run react-doctor”)
After completing React changes (if skill is installed)

Manually trigger:

npx react-doctor . --verbose --diff

See Using with Coding Agents for details.

Getting Help

If you’re still stuck:

Check GitHub Issues

Search existing issues: github.com/millionco/react-doctor/issues

Enable Verbose Mode

npx react-doctor . --verbose

Provides detailed diagnostics.

Run with Debug Info

DEBUG=* npx react-doctor .

Shows internal logs.

Open an Issue

Report bugs: github.com/millionco/react-doctor/issues/new Include:

React Doctor version (npx react-doctor --version)
Node.js version (node --version)
Operating system
Full error message
Command you ran

Most issues are Node.js version mismatches or Git configuration problems. Check those first!

Get Started

Usage

Rules Reference

Guides

Examples

​Node.js Version Issues

​Required Version

​Unsupported Node.js Version

​Option 1: Upgrade Node.js

​Option 2: Install via nvm (Recommended)

​Option 3: Use npx with Matching Node

​nvm Not Installed

​Native Binding Error

​Performance Issues

​Scan Takes Too Long

​Use Diff Mode

​Select Specific Project

​Disable Dead Code Detection

​Ignore Generated Files

​Knip Hangs or Times Out

​Installation Issues

​npx Command Not Found

​Permission Denied

​Slow Installation

​Score Calculation Issues

​Score Not Calculated

​Score Seems Wrong

​Score Doesn’t Improve After Fixes

​Configuration Issues

​Config Not Loaded

​Invalid Config Format

​Rules Still Appearing After Suppression

​Git and Diff Mode Issues

​”Not a git repository”

​No Changed Files Detected

​Base Branch Not Found

​CI/CD Issues

​GitHub Actions: fetch-depth Error

​CI Hangs or Times Out

​CI Fails with Exit Code 1

​Monorepo Issues

​Workspaces Not Detected

​Project Not Found

​Scanning Takes Too Long in Monorepo

​Output and Display Issues

​Colors Not Showing

​Verbose Output Truncated

​JSON Output

​Coding Agent Integration Issues

​Skill Not Recognized

​Agent Doesn’t Run Automatically

​Getting Help

​Check GitHub Issues

​Enable Verbose Mode

​Run with Debug Info

​Open an Issue

Build docs developers (and LLMs) love

Node.js Version Issues

Required Version

Unsupported Node.js Version

Option 1: Upgrade Node.js

Option 2: Install via nvm (Recommended)

Option 3: Use npx with Matching Node

nvm Not Installed

Native Binding Error

Performance Issues

Scan Takes Too Long

Use Diff Mode

Select Specific Project

Disable Dead Code Detection

Ignore Generated Files

Knip Hangs or Times Out

Installation Issues

npx Command Not Found

Permission Denied

Slow Installation

Score Calculation Issues

Score Not Calculated

Score Seems Wrong

Score Doesn’t Improve After Fixes

Configuration Issues

Config Not Loaded

Invalid Config Format

Rules Still Appearing After Suppression

Git and Diff Mode Issues

”Not a git repository”

No Changed Files Detected

Base Branch Not Found

CI/CD Issues

GitHub Actions: fetch-depth Error

CI Hangs or Times Out

CI Fails with Exit Code 1

Monorepo Issues

Workspaces Not Detected

Project Not Found

Scanning Takes Too Long in Monorepo

Output and Display Issues

Colors Not Showing

Verbose Output Truncated

JSON Output

Coding Agent Integration Issues

Skill Not Recognized

Agent Doesn’t Run Automatically

Getting Help

Check GitHub Issues

Enable Verbose Mode

Run with Debug Info

Open an Issue