Skip to content

Reference

Troubleshooting

The failure modes you'll actually hit: shallow clones under changed-only, rate limits, unknown verdicts, cache staleness, and exit-code debugging.

"Cannot resolve base ref" under --changed-only

The diff needs the merge-base of HEAD and the base ref, and a shallow clone doesn't have it. In GitHub Actions, check out with history:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

Locally, git fetch origin main (or whatever your base is) before running. The error message names the ref it tried and this exact fix.

Lots of unknown fields / rate-limit warnings

GitHub enrichment (archived state, last push) is unauthenticated without a token, and shared CI runners exhaust the anonymous rate limit quickly. Set GITHUB_TOKEN — in Actions the default workflow token is enough; it only reads public repo metadata. This is a degradation, never a failure: fields become unknown, the run completes, and only rules with actual evidence fire.

A package is flagged and you disagree

Follow the evidence link in the finding — every claim cites its source (npm, the RN Directory, GitHub). If the source is wrong (directory data lags reality sometimes), add an allow entry to unblock yourself and file a correction upstream. If the source is right, well — the tool did its job.

Stale verdicts after a package was updated

Enrichment is cached in .rn-doctor-cache.json for 24 hours. --no-cache forces fresh data (bypasses both read and write), or delete the file. Make sure the cache file is gitignored — committing it pins yesterday's registry state into everyone's runs.

Exit code 2 when you expected findings

2 means the tool itself failed, not the policy: bad flags, unreadable package.json, an invalid policy file (including unknown keys — strict on purpose), --base without --changed-only, a git failure, or missing workspace configuration under --workspaces. The stderr message names the cause; policy findings always exit 0 or 1.

The annotation points at a weird line

Annotations resolve the dependency's line with a string-escape-aware JSON walker scoped to the dependencies block, so same-named keys under scripts or devDependencies can't false-match. If a line is still off, the package.json probably changed between checkout and run — check for steps that rewrite it (version bumps, npm pkg set) before the check.