Reference
Debugging
The debugging skill provides knowledge for diagnosing problems in React Native apps using the CDP MCP server, native device logs, and bash tools.
When loaded
Section titled “When loaded”Activates when Claude encounters crashes, blank screens, connection issues, error logs, Metro problems, network failures, or any diagnostic task.
Key Knowledge Areas
Section titled “Key Knowledge Areas”CDP vs Bash Decision Table
Section titled “CDP vs Bash Decision Table”| What you need | Tool | Command |
|---|---|---|
| Metro status | MCP | cdp_status |
| JS crash | MCP | cdp_error_log |
| Native crash (iOS) | MCP | collect_logs(sources=["native_ios"]) |
| Native crash (Android) | MCP | collect_logs(sources=["native_android"]) |
| Current screen | MCP | cdp_navigation_state |
| Component tree | MCP | cdp_component_tree(filter="...") |
| Store state | MCP | cdp_store_state(path="...") |
| API calls | MCP | cdp_network_log |
| Console output | MCP | cdp_console_log(level="all") |
| RedBox overlay? | MCP | cdp_component_tree (auto-detects) |
| Metro alive? | MCP | cdp_status |
| UI element tree | MCP | device_snapshot |
| Runtime value | MCP | cdp_evaluate(expression="...") |
If cdp_error_log is empty but the app is broken, the problem is native.
Error Types Matrix
Section titled “Error Types Matrix”| Error Type | Where to Find |
|---|---|
| JS runtime error | cdp_error_log |
| Unhandled promise rejection | cdp_error_log |
| RedBox overlay | cdp_component_tree (APP_HAS_REDBOX) |
| console.error() | cdp_console_log(level="error") |
| Metro bundle syntax error | cdp_metro_events |
| Native crash (iOS) | collect_logs(sources=["native_ios"]) |
| Native crash (Android) | collect_logs(sources=["native_android"]) |
| Network failure | cdp_network_log (status=0) |
Environment authority and health
Section titled “Environment authority and health”Call rn_session(action="status") first, then passive cdp_status.
- Missing Metro or bundle binding means repair the session through the integrated package script.
- A disconnected exact target means open the bound app and call
cdp_connect. - Use
cdp_component_treefor helper and RedBox health. - Use
cdp_error_logfor active JavaScript errors. - For
HELPERS_NOT_INJECTED, read boundedmeta.helperHealthand follow the packaged debugging skill’s recovery order; a probe timeout does not prove a JavaScript hang.
Connection Troubleshooting
Section titled “Connection Troubleshooting”| Symptom | Fix |
|---|---|
| Metro not found | Inspect rn_session, then use literal pnpm ios or pnpm android |
| No Hermes target | Wait for the bound app to load, then call cdp_connect |
| Error code 1006 | Close other debugger UIs (DevTools, Flipper, Chrome) |
| Evaluate timeout (5s) | Search for debugger; statements, check for long sync ops |
| ”hook not available” | Only works in __DEV__ mode with Hermes |
| APP_HAS_REDBOX | Read error log, fix code, reload |
| ”No store found” | Add if (__DEV__) global.__ZUSTAND_STORES__ = { ... } |
| All CDP calls fail | Reload the bound app and reconnect with cdp_connect |
CDP Technical Constraints
Section titled “CDP Technical Constraints”- 5-second timeout on all CDP calls (caused by
debugger;statements, long sync ops, unresolved promises) - Single CDP session (Hermes allows exactly one client; close DevTools/Flipper first)
- Fiber tree limitations: only works in
__DEV__+ Hermes; component in tree does not mean visible on screen
Post-Reload Readiness
Section titled “Post-Reload Readiness”After cdp_reload, auto-reconnect waits up to 30 seconds. If cdp_component_tree returns “No fiber roots”, wait 2 seconds and retry.
Metro Health Check
Section titled “Metro Health Check”Call rn_session(action="status") to inspect the bound Metro authority, then use cdp_status for passive runtime health and cdp_metro_events for bundle failures. Ambient default ports are diagnostic only and never establish session authority.