Troubleshooting

Connection issues

Metro not found

Start Metro first: npx expo start or npx react-native start. The plugin auto-detects ports 8081, 8082, 19000, and 19006.

No Hermes target

Open the app on the simulator and ensure Hermes is enabled. Check your app.json or metro.config.js for Hermes configuration.

CDP connection rejected (1006)

Close React Native DevTools, Flipper, or Chrome DevTools — only one debugger can connect at a time. The 1006 close code means session conflict.

CDP connection lost after reload

This is normal. cdp_reload automatically reconnects within 15 seconds. If it fails, call cdp_status to re-establish the connection.

Store state issues

cdp_store_state error for Zustand

Run /rn-dev-agent:setup — it scaffolds the dev-bridge and proposes a getBridge()?.registerStores({ ... }) line in your app entry. The bridge call replaces the older globalThis.__ZUSTAND_STORES__ pattern.

Manual fallback if you want to wire it yourself:

import { getBridge } from './.rn-agent/dev-bridge';

getBridge()?.registerStores({
  auth: useAuthStore,
  cart: useCartStore,
});

Redux is auto-detected — no setup needed.

cdp_store_state returns empty for React Query

Use storeType: 'react-query' explicitly. React Query state is read from the QueryClient, which requires the provider to be mounted.

Plugin issues

Plugin not detected

Run /plugin install rn-dev-agent@Lykhoyda-rn-dev-agent then /reload-plugins. For local development, use claude --plugin-dir /path/to/rn-dev-agent.

/plugin command not found

Update Claude Code to v1.0.33+: npm update -g @anthropic-ai/claude-code

Plugin skills not appearing

Run /reload-plugins or clear cache: rm -rf ~/.claude/plugins/cache

Plugin update fails with ENOTEMPTY

Clear the stale cache first:

rm -rf ~/.claude/plugins/cache/Lykhoyda-rn-dev-agent

Then retry the update.

ENAMETOOLONG on install/update

Clear stale cache:

rm -rf ~/.claude/plugins/cache/Lykhoyda-rn-dev-agent ~/.claude/plugins/data/rn-dev-agent-*

Then re-add marketplace and install.

Device issues

maestro-runner not in PATH

Add to your shell profile: export PATH="$HOME/.maestro-runner/bin:$PATH"

Empty error log but app crashed

The crash is native, not JavaScript. Use adb logcat -b crash (Android) or check Xcode console (iOS) for native crash logs.

Android emulator not detected

Ensure the emulator is booted and adb devices shows it. The plugin auto-selects the first available device. Set ANDROID_SERIAL to target a specific emulator.

Maestro gRPC error on Android

Use maestro-runner instead of classic Maestro — it uses HTTP to UIAutomator2 instead of gRPC. The plugin enforces this by default.

Actions and setup

Action replay fails with SELECTOR_NOT_FOUND

The plugin attempts to self-repair small UI drift: it looks at the live UI, finds the renamed testID via fuzzy match, patches the action YAML, and retries.

Self-repair refuses if the file has been hand-edited (mtime check), or after 3 repairs in 24h. If repair is refused or fails, the plugin asks before forcing. If the underlying flow has changed structurally (extra step, removed screen), re-record with /rn-dev-agent:test-feature.

See the Actions guide for full details.

`/setup` skipped a step

Re-run /rn-dev-agent:setup. It’s idempotent — already-injected blocks are detected and skipped, so only the missing pieces get applied.

.rn-agent/state/ showing up in git status

That directory holds runtime state (run history, repair history) — not config. Check that .rn-agent/.gitignore exists and contains state/, recordings/, snapshots/, diag/, index.json. The /setup scaffold ships this file; if it’s missing, regenerate via /setup (idempotent — only the missing pieces are added).