Troubleshooting

ceraph start runs a readiness check as its final step and stops at the first failed gate with a concrete fix. Here are the errors you're most likely to hit, and how to clear them.

Taps do nothing — the device is locked or asleep

A real iPhone must be awake and unlocked for automation to land. When it is locked, taps silently no-op. Unlock the phone (and keep it awake) before driving.

The guided ceraph start exists for exactly this hands-on device bring-up — unlocking and entering a passcode are the moments that need a human.
If your app has expo-keep-awake (installed by default in the Expo SDK) or react-native-keep-awake, Ceraph keeps the screen awake during runs. Add it to an Expo app with:
```
npx expo install expo-keep-awake
```

WebDriverAgent isn't reachable (real device)

On a real device, Ceraph reaches WebDriverAgent at localhost:8100, port-forwarded from the phone by Xcode. WebDriverAgent installs through Xcode the first time (one-time setup).

If WDA is unreachable while a device is connected, Ceraph auto-forwards the port with iproxy. When iproxy isn't installed, install libimobiledevice:

brew install libimobiledevice

On a simulator you don't manage WDA yourself: ceraph start installs the optional appium-webdriveragent dependency and builds + launches WebDriverAgent for you the first time you target a simulator. The first build is a one-time minute or so; later runs reuse the cache.

The app can't load its JS bundle (Metro isn't running)

The app loads its JavaScript from Metro. Let ceraph start manage Metro for you — it starts the dev server as part of bring-up, so you don't launch it by hand:

ceraph start

Expo Go can't load a Ceraph-instrumented build — use an Expo dev client or a prebuilt app. If the connection to Metro drops (laptop sleep, a Metro restart, a network blip), Fast Reload reconnects the app on its own the moment Metro is back; you'll see [ceraph-fast-reload] reconnected after Metro disconnect in the console.

Port collision on a shared Mac

Ceraph's on-device signal listener binds to localhost:8101 (WebDriverAgent uses 8100, Metro uses 8081). Only one developer on a given Mac can run the MCP at a time without a collision. If you share a Mac and need parallel sessions, override the port when starting the MCP server:

export CERAPH_SIGNAL_PORT=8102

Still stuck?

The README is the full reference — every tool, environment variable, and the camera / hooks setup, plus the diagnostics ceraph start runs for you: @ceraph/react-native-mcp on npm.