REA Troubleshooting & Diagnostic Manual
Official REA (rea-agents) diagnostics address: Ghidra startup timeouts (fixed via REA_GHIDRA_STARTUP_TIMEOUT_MS), Hopper bridge socket failures (diagnosed via rea doctor), agent backup write permission errors (repairable via .rea.backup), and macOS EACCES admission errors. Run rea doctor for comprehensive local healthchecks.
What is the relationship between REA (rea.tools) and How to REA (howtorea.com)?
<strong>Official REA:</strong> The core open-source project is developed by morluto, hosted at github.com/morluto/rea with official website at rea.tools. It distributes the <code>rea-agents</code> NPM package.
<strong>How to REA (howtorea.com):</strong> An independent, peer-reviewed open community technical handbook and interactive documentation companion. While rea.tools provides core project information, howtorea.com expands the ecosystem with interactive visual MCP generators for 12+ coding agents, deep-dive catalogs across 29 reverse-engineering tools, and verified clean-room deconstruction guides.
ERR_01Analysis operation timed out after {timeoutMs}ms
<strong>Trigger:</strong> Disassembling large native binaries (50MB+) in Ghidra or Hopper exceeds the default startup or decompilation deadline.
<strong>Root Cause:</strong> Ghidra HeadlessScript requires extensive memory and CPU time to build symbols and cross-reference graphs on cold start.
<strong>Resolution:</strong> Increase the startup timeout in your environment, or pass a specific function address rather than requesting a full binary dump:
# Extend Ghidra timeout to 60 seconds
export REA_GHIDRA_STARTUP_TIMEOUT_MS=60000
# Or pass directly to one-off CLI call
REA_GHIDRA_STARTUP_TIMEOUT_MS=90000 rea function ./large-binary main --provider ghidraERR_02Hopper bridge stopped unexpectedly with exitCode / HopperRemoteError
<strong>Trigger:</strong> REA fails to communicate with Hopper Disassembler via Unix-domain sockets (<code>bridge/hopper_bridge.py</code>).
<strong>Resolution:</strong> Verify Hopper installation path and launch permissions using <code>rea doctor</code>:
rea doctor --provider hopper
# If Hopper is missing on macOS, allow setup to install verified vendor package:
npx rea-agents setup --provider hopperERR_03Agent configuration backup verification failed
<strong>Trigger:</strong> Running <code>npx rea-agents setup</code> fails when trying to create a transactional backup of your existing agent configuration (e.g. <code>claude_desktop_config.json</code> or <code>~/.cursor/mcp.json</code>).
<strong>Resolution:</strong> Inspect permissions on the client directory, or test with a dry run to inspect the proposed plan without writing:
# Check the proposed setup transaction without writing
npx rea-agents setup --client cursor --dry-run --json
# If corrupted, restore the automatic backup created previously:
cp ~/.cursor/mcp.json.rea.backup ~/.cursor/mcp.jsonERR_04Cannot open artifact: EACCES permission denied on macOS .app
<strong>Trigger:</strong> Attempting to inspect applications located inside <code>/Applications/Target.app</code> on macOS Sonoma or Sequoia.
<strong>Resolution:</strong> Modern macOS restricts access via App Sandbox and TCC. Copy the target bundle into a local working directory or temporary path before analysis:
cp -R /Applications/TargetApp.app /tmp/TargetApp.app
rea analyze-javascript-application /tmp/TargetApp.app/Contents/Resources/app.asar --json