rn-debugging

name: rn-debugging description: This skill should be used when the user asks to "debug the app", "fix a crash", "diagnose a blank screen", "read error logs", "troubleshoot CDP connection", "check Metro status", "find native crashes", "inspect network failures", "the app crashed", "I see a blank screen", "the screen is white", "something broke", "app won't load", "RedBox error", "network requests failing", or needs guidance on CDP vs bash debugging, error type identification, connection troubleshooting, or post-reload readiness for React Native apps.

rn-debugging — CDP Usage, Error Identification, and Connection Troubleshooting

How to diagnose problems in React Native apps using the CDP MCP server, native device logs, and bash tools.

CDP vs Bash Decision Table

Key rule: If cdp_error_log is empty but the app is visibly broken, the problem is native. CDP only sees JavaScript — check native logs as fallback.

Error Types Matrix

Note: Replace "/YourApp" with the actual binary name and com.example.app with the real bundle ID. Find the binary name: ls $(xcrun simctl get_app_container booted <bundle-id>)

Environment Status Check (Always First)

Before any testing or debugging, call cdp_status. It returns:

{
  "metro": { "running": true, "port": 8081 },
  "cdp": { "connected": true, "device": "iPhone 16 Pro", "pageId": 3 },
  "app": {
    "platform": "ios", "dev": true, "hermes": true,
    "rnVersion": "0.83.1",
    "dimensions": { "width": 393, "height": 852 },
    "hasRedBox": false, "isPaused": false, "errorCount": 0
  },
  "capabilities": {
    "networkDomain": true, "fiberTree": true, "networkFallback": false
  }
}

Decision tree:

• metro.running = false → start Metro: npx expo start or npx react-native start
• app.hasRedBox = true → read cdp_error_log, fix the error, then cdp_reload
• app.isPaused = true → cdp_reload (auto-reconnects after reload)
• app.errorCount > 0 → check cdp_error_log before continuing
• capabilities.networkDomain = false → network logging uses injected hooks (RN < 0.83)
• capabilities.fiberTree = false → release build or non-Hermes engine

Connection Troubleshooting Guide

Code 1006: Hermes allows only one CDP client. Close all debugger UIs first. Code 1001: Normal close from a reload — handled automatically, no action needed.

Recovering from HELPERS_NOT_INJECTED

When a cdp_* tool returns code: HELPERS_NOT_INJECTED, the bridge has already done all of this:

1. Waited up to 5s for the connect-time injection to flip the flag
2. Actively re-injected __RN_AGENT once with a 3s React-ready timeout
3. Attempted a Dev Client picker dismissal (in case a native overlay was blocking React)
4. Waited up to another 30s if the picker was dismissed

So when this error appears, the JS world is genuinely hung — Hermes is up but __RN_AGENT won't land. Two recovery paths, in order:

Anti-pattern: retrying cdp_status in a loop. The connection is up; status calls don't re-trigger injection in this state — they return immediately and let you spin. The error code is the signal to change strategy, not to wait longer.

Post-Reload Readiness

After cdp_reload, the server auto-reconnects and waits up to 30 seconds for React DevTools hook. If cdp_component_tree returns "No fiber roots" immediately after reload, wait 2 seconds and retry.

Manual readiness check:

cdp_evaluate(expression="typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ !== 'undefined' && __REACT_DEVTOOLS_GLOBAL_HOOK__.renderers?.size > 0")

CDP Technical Constraints

5-Second Timeout on All Calls

Every CDP call has a hard 5-second timeout. Common causes of timeout:

• debugger; statement in code
• Long synchronous computation
• Unresolved promise with awaitPromise=true
• Metro busy bundling

Single CDP Session

Hermes allows exactly one CDP client at a time. Things that consume a session:

• React Native DevTools (built into RN 0.73+)
• Flipper (older projects)
• Chrome DevTools connected via Metro
• The MCP server itself

Fiber Tree Limitations

• Only works in __DEV__ builds with Hermes engine
• Component in fiber tree does NOT mean visible on screen
• Full tree dumps are expensive — always use filter parameter

Common Error Patterns

For diagnostic recipes covering "Cannot read property X of undefined", "Invariant Violation", native crashes with no CDP error, truncated results, and missing network requests, consult references/common-error-patterns.md.

Metro Health Check

curl localhost:8081/status          # Expected: "packager-status:running"
curl localhost:8081/json/list       # List Hermes debug targets
curl localhost:19000/status         # Expo alternative port (Expo Dev Client)

The MCP server auto-discovers Metro on ports 8081, 8082, 19000, 19006. Pass metroPort to cdp_status when using non-standard ports.

Native Log Commands

For full native log command reference (iOS log stream, Android logcat, binary name discovery), see the rn-device-control skill.

Common Rationalizations

Agents routinely skip diagnostic steps because "the problem looks obvious." Don't.

Red Flags — Stop and Reconsider

If you notice yourself doing any of these, stop and reassess:

• Editing code without having read cdp_error_log + cdp_component_tree first
• About to run xcrun simctl or adb logcat directly instead of collect_logs
• Claiming "fixed" without running the reproduction steps again
• Declaring "looks fine now" based on a screenshot alone — check store state too
• Suggesting a reload without having identified the actual bug
• Adding try/catch to silence the error instead of understanding it

Verification — Before Declaring a Fix Complete

• cdp_status returns ok:true with no errors
• Reproduction steps executed AGAIN after the fix → bug no longer reproduces
• cdp_error_log(clear: true) → cdp_error_log() shows zero new errors
• If the bug showed symptoms on screen, device_screenshot now shows expected state
• If the bug was state-related, cdp_store_state(path="<slice>") returns expected shape
• Cross-platform: check the same flow on the OTHER platform (cross_platform_verify)

Additional Resources

• references/common-error-patterns.md — Diagnostic recipes for common RN errors
• references/navigation-patterns.md — Navigation debugging: modal→tab navigation (B75), nested navigator patterns, CDP navigate usage
• references/capability-matrix.md — CDP feature support by React Native version