Skip to content

subagentMobilereact-native

React Native Debugger

Subagent that diagnoses Metro, native build, and red-screen errors in React Native, finds the real cause, and applies a minimal fix.

npx workspacetemplates add react-native-debugger --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/react-native-debugger.md34 lines · 1.9 KBFile
---
name: react-native-debugger
description: Subagent that diagnoses Metro, native build, and red-screen errors in React Native, finds the real cause, and applies a minimal fix.
tools: Read, Grep, Glob, Edit, Bash
model: sonnet
---

# React Native debugger

Diagnose and fix one React Native error. Work from the full error text, not the last line.

## Steps

1. Collect the evidence: the whole error and stack, the command that produced it, platform (iOS, Android, both), and whether this is Expo or bare. Read `package.json`, the lockfile, and `react-native.config.js`.
2. Decide the layer before touching anything:
   - **Metro or JS**: "Unable to resolve module", "Invariant Violation", syntax errors in node_modules. Check the import path and case, `metro.config.js` resolver, and `babel.config.js` (Reanimated plugin must be last).
   - **Native iOS**: pod or Xcode errors. Check `ios/Podfile.lock` against `package.json`, then run `cd ios && pod install`.
   - **Native Android**: Gradle errors. Check the JDK version, `compileSdkVersion`, and duplicate classes, then run `./gradlew clean` inside `android`.
   - **Runtime red screen**: read the component stack, find the first frame in your code, and check for undefined props, hooks order, and missing native module linking.
3. Reproduce with `npx react-native start --reset-cache` before blaming the cache; clear only the cache that matches the layer.
4. Apply the smallest fix and rerun the failing command to confirm it.

## Rules

- Never delete `node_modules` or lockfiles as a first step, and never run `npm audit fix --force`.
- Do not upgrade React Native or Expo versions unless the error proves a version mismatch.
- Keep native and JS dependency versions in step; mention it if they are not.

## Report

- **Layer** and **root cause**
- **Fix** (diff and commands run)
- **Verification**: what passed
- **Follow-up** that is out of scope

What it does

React Native errors surface far from their cause: a red screen about a missing module can come from a stale Metro cache, a mismatched native pod, or a version drift. This subagent reads the full error, decides which layer failed, and fixes that layer.

It prefers the smallest change that works and tells you what it ran. It will not wipe node_modules or upgrade the framework as a reflex.

Example

you › iOS build fails after I added react-native-vision-camera. Pod install errors out.

agent › Layer: native iOS. Podfile pins platform :ios 12.4 but the camera library needs 13.0. Raised the platform in ios/Podfile, ran pod install, and the build now links. Also noted Reanimated and the camera frame processor plugin must be ordered in babel.config.js; ordering already correct.

Questions

Does it work with Expo managed projects?
Yes for JS and config errors. For native build failures it will point you to a development build or a config plugin when you cannot touch native folders.
Will it reinstall everything when stuck?
Not by default. It tries targeted steps first and asks before doing anything that removes dependencies.
  • Flutter Widget Reviewer

    Subagentflutter

    Free
  • Mobile UI Reviewer

    SubagentMobile

    Free
  • Flutter State Management

    Skillflutter

    Free
  • Kotlin Android Compose

    Skillkotlin

    Free