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.

No inline annotations appear

The platform is auto-detected from GITHUB_ACTIONS, TF_BUILD, GITLAB_CI or BITBUCKET_BUILD_NUMBER. Force one with --ci <platform> and check nothing in the pipeline passes --no-annotations. Platform-specific gotchas:

  • Azure Pipelines: paths in ##vso commands are repo-relative, so run rn-doctor from the repository root. Notes and allowlisted findings are intentionally omitted - Azure has no notice level and warnings inflate the run's issue count. They remain in the pretty log.
  • GitLab: the merge-request widget needs the artifact declared under artifacts: reports: codequality; writing the file with --gitlab-codequality isn't enough on its own. The widget diff shows findings new to the branch; the pipeline's Code Quality tab has the full list.
  • Bitbucket: Code Insights go through the Pipelines-local auth proxy, which exists only inside a running pipeline. Elsewhere rn-doctor warns and continues; the upload can never change the exit code.

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.