Troubleshooting: Errors We Actually Hit

No theoretical error catalog here — every entry below happened in a real session on macOS, [email protected], November 2026.

cleanup_incomplete — analysis finishes but --evidence_output is never written

Symptom: analyze-web-bundle reports full results (all scripts parsed, AST stats in the output), then exits with:

code: cleanup_incomplete
category: execution_failure
message: Provider cleanup could not be fully confirmed.
  reason: Owned web analyzer cleanup remains incomplete

…and the path you passed to --evidence_output does not exist. The output also names leftover temp resources like /T/rea-web-bundle-analysis-XXXX.

Cause: REA treats evidence integrity seriously — if it cannot confirm its analyzer worker fully exited, it refuses to write the bundle rather than write an unverified artifact. We saw this consistently when running REA inside a sandboxed shell environment (restricted process supervision, GPU/sandbox helper failures in child processes).

Workaround: the complete evidence envelope is still printed to stdout. Capture it directly:

npx rea-agents@latest analyze-web-bundle http://127.0.0.1:9222 <TARGET_ID> \
  --allowed-origins https://your-target.example.com \
  --detail complete --format json --full-output > evidence.json

The resulting JSON contains the full observation: source manifest with SHA-256 hashes, route inventory, unknowns, statistics and limitations. Running REA from a normal terminal (outside sandbox wrappers) should also let --evidence_output succeed — we'd expect the strictness to be the difference.

cdp_endpoint: invalid_value on list-browser-targets

Symptom:

npx rea-agents@latest list-browser-targets 127.0.0.1:9222
→ issues[1]: path[1]: cdp_endpoint, reason: invalid_value

Fix: include the scheme: list-browser-targets http://127.0.0.1:9222. A WebSocket URL also works.

Browser refuses --remote-debugging-port on your default profile

Symptom: Edge/Chrome 136+ launches fine, but nothing listens on the debug port, and /json/version is unreachable.

Fix: Chromium-based browsers now block the debug port on the default user profile. Pass a dedicated directory: --user-data-dir="$HOME/rea-debug-profile". Bonus: this keeps your daily browser untouched.

EBADENGINE warning on install, doctor flags Node

Symptom: npm warn EBADENGINE required: ^22.23.4 || ^24.22.1 || >=26.12.1, and rea doctor reports the node check as missing_dependency.

Fix: cosmetic until it isn't — the CLI runs on slightly older Node 22, but upgrade to a version inside the declared range for a clean doctor report.

--view confusion with --detail summary

Symptom: a chain of unhelpful validation errors: view must be valid JSON → view,collection missing, expected: summary,routes,occurrences,sources,unknowns → view,kind invalid, expected: javascript-routes.

Fix: the correct form is --view '{"kind":"javascript-routes","collection":"routes"}'. Or skip the ceremony entirely and use --detail complete.