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 physical iOS or Android device must be awake and unlocked for automation to land. Unlock the phone before driving and handle any passcode, trust, or USB-debugging prompt.

If you expect to step away, run ceraph start ahead of testing to prime the device while you are present to unlock it and handle any passcode or trust prompts.
Ceraph manages development-only keep-awake protection itself; you do not need another package. It preserves and restores the Android device's existing stay-awake and screen-timeout settings.

UiAutomator2 or ADB isn't reachable (Android)

Confirm the selected Android runtime is online and authorized. A physical device should appear with a USB transport, while an emulator appears as an emulator target:

adb devices -l

If it says unauthorized, unlock the phone and accept its USB-debugging prompt. If ADB is stale, restart it and run ceraph start --android again. Ceraph manages Appium, UiAutomator2, port allocation, and the required ADB reverse mappings; do not start a separate driver server.

adb kill-server && adb start-server

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 host

Ceraph's on-device signal listener uses host port 8101 by default, while Metro usually uses 8081. WebDriverAgent also uses 8100 on iOS; Android driver ports are allocated and managed for the exact runtime. Sessions in the same project can share Ceraph. When running unrelated projects concurrently, give each project its own signal port:

CERAPH_SIGNAL_PORT=8102 ceraph start

In PowerShell, use $env:CERAPH_SIGNAL_PORT=8102; ceraph start instead.

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.