Troubleshooting
Every doctor check with its fix, and the error codes Parallax tools return, each with a cause and a fix.
Start with doctor. Ask your agent to call it, or run it yourself in your app's project root:
npx -y @parallax-rn/mcp@0.1.0-beta.2 doctorThe command prints to stdout. It prints one line per check as [ok], [warn] or [fail], and a Fix: line under each check that is not ok. It says whether the device tools (screen and input) and the app tools (logs, errors, tree, data) are ready, separately. The exit code is 1 when a check fails. If nothing explains the problem, send a diagnostics report.
Doctor checks
A fail blocks the tools it affects. A warn is something to know or fix that blocks nothing. A missing SDK or build plugin is only a warning: the device tools work without them.
Device tools
| Check | What it means | Fix |
|---|---|---|
| Xcode command line tools | xcode-select -p answers | Install them: xcode-select --install (or install Xcode and run sudo xcode-select -s /Applications/Xcode.app) |
| Simulator control (simctl) | xcrun simctl lists simulators | Install Xcode (the simulator ships with it) and run xcodebuild -runFirstLaunch once |
| AXe | AXe is installed and is version 1.8 or later | Install: brew install cameroncooke/axe/axe. Upgrade: brew upgrade cameroncooke/axe/axe |
| Booted simulator | At least one simulator is booted | Open the Simulator app, or xcrun simctl boot <id> (ids: xcrun simctl list devices) |
| Xcode version | Verified on Xcode 27.0; other versions show a warning | Tools that use private Apple frameworks can change between Xcode releases. If the device tools misbehave, report which Xcode this is |
| Simulator input surface | Information: Xcode's Devices window is attached to a simulator (closing it shuts the simulator down) | None needed |
| Screen helper | The helper behind the window's live picture and fast input. None found is information only. A warning means the helper file changed after it was built, or the Xcode is not one it was verified on | Reinstall the Parallax app. If the screen or input misbehaves, the agent's tools still work through AXe; report the Xcode version |
| Android adb, Android emulator, Android AVDs, Booted emulator | Only for Android. "Android: SDK not found" is information when you use no emulator | Install Android Studio or the command-line tools, or set ANDROID_HOME. Create an AVD in Android Studio's Device Manager; boot it with Boot in the window or emulator -avd <name> |
| AXe helper (hid-broker) | A background process AXe starts on the first touch. A warning means one is running with no Parallax core to own it | Harmless: AXe starts it again when needed. To stop it: pkill -f 'axe hid-broker' |
Parallax core and agent setup
The Session hooks, Answer hooks and Agent route rows are printed only by the command line doctor, not by the agent's doctor tool. The Answer hooks row has no title of its own and shows as the raw label answer_hooks.
| Check | What it means | Fix |
|---|---|---|
| Parallax core | Which core answers: the window's, or one this server started itself. Fails when the window's core speaks another protocol | Update the Parallax app or the MCP package so they match |
| Terminal tab | Warns when the server cannot tell which Parallax terminal tab its agent runs in (Codex's shared daemon) | Start Codex with codex --no-daemon in a Parallax terminal tab |
| Approvals | Strict mode on or off. Warns when strict mode is on and the window is not running | Open the Parallax window, or turn strict mode off: npx -y @parallax-rn/mcp@0.1.0-beta.2 setup <agent> --undo --strict-approvals |
| Session hooks | Whether the optional session hooks are installed for each agent | npx -y @parallax-rn/mcp@0.1.0-beta.2 setup <agent> --hook (optional: without it the window's session list stays empty) |
answer_hooks | Whether the optional answering hook is installed | npx -y @parallax-rn/mcp@0.1.0-beta.2 setup <agent> --answer-approvals (optional) |
| Agent route | Which server each agent runs: the installed app, npm, or a checkout. Warns when the app's bundled server is missing | Reinstall the Parallax app, or move the registration back to npm: setup <agent> --undo, then setup <agent> --package @parallax-rn/mcp@0.1.0-beta.2 |
App tools
| Check | What it means | Fix |
|---|---|---|
| Metro | Metro answers at the address Parallax uses. Fails when nothing answers, or when what answers is not Metro's packager | Start Metro (for example npx react-native start), or point Parallax at it with --metro-url or PARALLAX_METRO_URL. Check the port |
| React Native version | Fails below 0.85. Warns when your version is newer or older than the tested list. Warns when it cannot find react-native from the project root | Upgrade to 0.85 or later. On a warning, other versions may work; if app_tree fails, report the versions status shows |
| App connection | An app is connected to Metro. Warns when its JavaScript is not answering (paused or busy) | Launch the app on a simulator with Metro running. If it is paused, resume it in the debugger; Parallax never resumes a pause |
| Metro ws library | Warns when this Metro's ws 7.5.12 will close the app's socket after about 16,000 messages (about 4.5 hours) | Restart the app now and then, or raise ws to 7.5.13 or later with an overrides or resolutions entry. Parallax never changes your project |
| Bundle build | Metro builds the app's bundle. Fails with the error and file when it does not | Correct the error (app_errors has the code frame); Metro rebuilds when you save. A warning means Metro is probably rebuilding: run doctor again |
| Parallax SDK | The SDK is running in the app, and its protocol is compatible | Install @parallax-rn/sdk and start it behind __DEV__, then reload. See Enable it in your app. "Not found yet" right after a reload: run doctor again |
| Parallax build plugin | The plugin's source tables are loaded and current | Add the plugin to babel.config.js (before react-native-worklets/plugin), restart Metro with --reset-cache, reload. "Stale" tables mean the plugin was updated without a cache reset |
| Parallax versions | The server, the SDK and the plugin have the same version | Update the older side. See Update and undo |
Error codes
Tool errors start with a stable code, then the message and a Fix: line.
Metro and the app
metro_unreachable
Nothing answers at Metro's address, or what answers is not Metro's dev server. Start Metro again; Parallax keeps retrying and reconnects by itself. Check the port.
no_app_target
Metro runs, but no app is connected to it, or Parallax could not attach. Launch the app in the simulator and check that it loaded the bundle from this Metro. For a second core on the same app, see Two agents: open the Parallax window so all agents share one core.
rn_unsupported
Your React Native does not report support for several debuggers per app (below 0.85, or a Metro that allows one). A second debugger would evict your DevTools. Upgrade to React Native 0.85 or later. In the window, Connect anyway takes the slot and disconnects DevTools.
reconnecting
The app disconnected (a crash or a restart) and Parallax is reconnecting. Retry shortly; the app has to be running again.
app_reloading
A reload ate the call. Retry: a reload is not a failure.
vm_paused
The app's JavaScript did not answer: it is paused in a debugger, or busy. Resume the pause in the debugger, or retry if the app is busy. Parallax never resumes a pause itself.
timeout
A step did not finish in time: the app did not connect, Metro was busy bundling, or the simulator was busy. Launch the app and start Metro, then try again.
The SDK, tree and commands
sdk_missing
The app has no Parallax SDK, or no such data source. The error names the call to add: start the SDK behind __DEV__, registerStore('main', store) for state, registerNavigation(navigationRef) for navigation. On Expo, network needs the SDK. See Network, state and navigation.
sdk_not_ready
The app has no Parallax SDK object yet; it may have just reloaded. Retry in a moment.
tree_unavailable
app_tree could not read the component tree. The message names the reason:
no_hook: the app has no React DevTools hook. Use a development build and reload.no_rendererorno_roots: React has not mounted yet. Retry in a moment.unexpected_shape: the React internals have a shape the reader does not know (it was checked on React Native 0.85 to 0.87 with React 19.2.3). Update Parallax; if it persists, report the versionsstatusshows.
command_not_found, command_failed
The app has no command with that name (list them with app_commands), or the command threw or returned something that is not JSON. See App commands.
The simulator
no_simulator
No available simulator has that id or name, or simctl failed. List the devices to see the ids, and check xcrun simctl list devices.
device_not_booted
The simulator is not booted. Boot it first (device_boot, or the Simulator app).
axe_missing
AXe is not installed, or returned output this version of Parallax does not know. Install or upgrade it: brew install cameroncooke/axe/axe (version 1.8 or later).
element_not_found
No element matches the id, label or text. The answer lists the closest elements on screen; correct the query. An ambiguous match is invalid_input.
app_not_frontmost
The app in front is the home screen or another app. Launch or open your app first.
invalid_input
An argument is wrong, for example a cursor that is not a next: value, or an ambiguous element. The message says what to correct.
Approvals and the core
denied_by_user
You declined an action in the window, or no Parallax window was open to approve it. The agent must not retry unless you ask. Open the window and ask again.
core_unavailable
The Parallax core did not answer, or went away while a call was in flight. The outcome of a call that was already sent is unknown: check the device (a screenshot or the UI tree shows what happened) before repeating it. Open the Parallax app or restart the agent.
core_version_mismatch
The window and the MCP server speak protocols that are too far apart. The message says which side to update: the Parallax app, or the MCP package (setup <agent> --update).
Android emulators
| Symptom | Fix |
|---|---|
| The emulator's screen stays black or "cannot be shown" | Check that adb devices lists it as device; on a fresh AVD wait until it has finished booting. |
| The app on the emulator shows "Unable to load script" | adb reverse tcp:<Metro port> tcp:<Metro port>, then reload. |
device_ui is slow on Android | Expected (about 2 s): uiautomator reads the whole screen. app_tree is faster for the React side. |
Try in this order
- Run
doctor. - After any plugin change, restart Metro with
--reset-cache:npx react-native start --reset-cache(bare React Native) ornpx expo start -c(Expo). - Look at the Metro
wsrow. - Close DevTools and other debuggers and see whether the symptom changes.
- Note whether the app is bare or Expo, and a development build or Expo Go.
Sending diagnostics
In the Parallax window: Help, Report a Problem… (or Copy Diagnostics… for the text alone). Report a Problem… copies the text and also opens a public issue form in your browser, so check what the text contains before you submit it. You read the text before it goes to the clipboard: versions, the checks and counts, the last core errors. It holds no log lines of your app, no prompts and no tokens. Add the React Native and Expo SDK versions, the Metro log around the failure, and the macOS crash report of your app if it crashed.