REA troubleshooting and FAQ

Unofficial guide. This site is an independent community guide and is not affiliated with the REA project. For authoritative docs see the official REA website and the morluto/rea GitHub repository. Commands here are taken from the official README/docs (checked 2026-10-13); REA changes quickly, so verify against the official docs.

Step 1: update first

The official advice: a recent release may already fix your bug.

rea update                    # global install
npx rea-agents@latest setup   # npx users

Restart your agent and retry.

Step 2: run a scoped readiness check

Problem area	Command
One agent registration	`rea doctor --client codex --json`
One analysis engine	`rea doctor --provider ghidra --json` (or hopper, ida)
Installed skill	`rea doctor --skill --json`
Static JS/Electron	`rea analyze-javascript-application PATH --json`

rea doctor is read-only. Without options it audits everything, so healthy can be false even when your workflow works — scope it.

Common issues

REA tools don't appear in Claude Code / Cursor

Restart the agent after setup; then run rea doctor --client <id> --json.

Setup refuses to write config

Malformed or unsafe existing configuration blocks the whole transaction. Repair the named setting in the client config file and rerun setup.

Node.js version error

Use Node.js 22.19+, 24.11+, or 26+.

Hopper on macOS waits forever

On first run Hopper may ask you to choose demo mode or activate a license. Complete that dialog in the same user session before your first REA operation.

`capability_unavailable`

Check details.selection_reason: ambiguous means choose a provider from details.candidate_ids (CLI --provider); provider_unavailable means repair that engine.

Large binary times out

Raise the startup deadline with REA_GHIDRA_STARTUP_TIMEOUT_MS or REA_HOPPER_STARTUP_TIMEOUT_MS.

Hopper not found on Linux

export HOPPER_LAUNCHER_PATH=/absolute/path/to/Hopper
rea doctor --provider hopper --json

Still stuck? Open an issue with your REA version, target type, steps and error output.

FAQ

Do I need Hopper, Ghidra or IDA?

Only for deep native-binary analysis. Static JavaScript and .NET inspection work without a native engine. Setup can install Hopper after approval; Ghidra and IDA use your existing installs.

Do I need to start Hopper first?

No, REA starts Hopper when needed. On macOS complete Hopper's first-run demo/license dialog once in the same user session.

Is rea doctor safe to run?

Yes, rea doctor --json is strictly read-only.

What should I include in a bug report?

Your REA version, target type, steps to reproduce and error output, after updating first.