# Failure Scenarios: Recovery Steps

When a debugger tool fails, use **`debugger-status`** first to diagnose. Then match the error or situation below and act as specified. Do not retry the same failing tool repeatedly without following the recovery steps.

| Scenario                           | Error or situation                                                                         | What to do                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Metro not running**              | Error contains: `Metro at port 8081 is not running (got: ...)`                             | **Start Metro yourself** unless the user asked you not to: scan the workspace configuration and run the appropriate command to start Metro in the background (by default `npx react-native start` or `npx expo start`). Wait for Metro to be ready, then retry `debugger-connect` or `debugger-status`. If you cannot determine the project root, ask the user. |
| **Metro not standard**             | Error contains: `Metro at port 8081 did not return X-React-Native-Project-Root header`     | Something on that port is not the standard React Native Metro server. Try starting Metro yourself from the app's project root using the command resolution above. If you cannot determine the correct root or the problem persists, inform the user what you found and what you tried.                                                                          |
| **App not connected**              | Error contains: `Metro at port 8081 has no CDP targets — is a React Native app connected?` | 1) Confirm the app is running on the device. 2) Use `restart-app` with the app's device id and bundleId to relaunch so it connects to Metro. 3) Wait a few seconds for the bundle to load. 4) Retry `debugger-status`. Do **not** use `debugger-reload-metro` to fix this — it also requires at least one target.                                               |
| **Was connected, then tool fails** | Any debugger tool fails with a connection or disconnect error after it was working         | The app may have crashed or been closed. Use `restart-app` to relaunch the app, then call `debugger-connect` again to pick up the fresh `logicalDeviceId` (may change for booted-fresh simulators), and use that new `device_id` on all subsequent calls.                                                                                                       |