Reference
Troubleshooting
Every receipt that is not a pass carries failure.code, failure.detail and a
next_action. Start with next_action; it names the exact step for that run. The report at
~/.qaren/runs/<run-id>/report.md shows each walked line.
Refusals exit 4 and mean the run could not start or could not decide; failures exit 1.
Before the walk
Section titled “Before the walk”| Code | What happened | What to do |
|---|---|---|
PLAN_UNPARSEABLE | A plan line has no step or check the grammar knows | Fix each listed line; see Write a plan |
PLAN_INPUT_MISSING | A runtime input is unset or empty, or a PR login block names an undeclared one | Set each listed QAREN_INPUT_<NAME>; see Runtime inputs |
JEV_UNREACHABLE | The plan needs Jev and the readiness probe did not succeed | Set a valid TYPESAFE_API_KEY, or quote every target and ✓ line |
JEV_AUTH_FAILED | Jev rejected the key | Check TYPESAFE_API_KEY |
SCENARIO_UNREADABLE | .qaren/config.yaml cannot be read | Create it with at least appId |
SCENARIO_INVALID | The configuration does not parse or fails validation | Fix the key a validation detail names; see Configuration |
DEV_CLIENT_SCHEME_REQUIRED | devClientScheme is missing or malformed | Set it to the app’s registered URI scheme |
NODE_UNSUPPORTED | Node is older than 24 | Point nodePath at Node 24 or newer |
DISK_BUDGET_EXCEEDED | Under 1 GiB free for ~/.qaren/runs or the app, or under about 10 GiB for a clean iOS build | Free space on the volume failure.detail names, then re-run |
Devices
Section titled “Devices”For FRESH_INSTALL_ADMISSION_UNKNOWN or a strict-admission DEVICE_BUSY, read the
probe diagnostics in failure.detail; see the authoritative
fresh-install contract
and iOS admission diagnostics.
| Code | What happened | What to do |
|---|---|---|
DEVICE_UNAVAILABLE | No booted simulator, more than one, or the named one is not booted | Boot the simulator to walk on, or shut down the ones you are not testing on |
DEVICE_UNAVAILABLE | On Android: no adb server answering, a version mismatch, or not exactly one booted emulator | Start the emulator, or pass --device emulator-NNNN |
DEVICE_BUSY | Another run holds the device’s lease | Wait for that run to finish, or clean it up with qaren cleanup <its-run-id>; a live holder is never stolen |
ARTIFACT_INSTALL_FAILED | The cached dev-client verification or installation failed | Follow next_action; see the cached-install recovery contract |
APP_EXITED_AT_LAUNCH | The launched app exited before it became ready; on iOS the detail cites the simulator crash report | Follow next_action, which for a missing app-embedded framework is a CocoaPods reinstall; see the launch readiness contract |
During the walk
Section titled “During the walk”| Code | What happened | What to do |
|---|---|---|
PLAN_STEP_FAILED | A step or check failed; the detail names the line and what was seen | Read the report, fix the app or the plan, then re-run |
CORE_REFUSED | The screen layer refused; the detail starts with its own code | Resolve that refusal, then re-run |
BLOCK_START_MISSING | The block’s declared start was absent; this is a typed refusal with exit code 4 | Follow the saved-block contract |
WALK_DEADLINE_EXCEEDED | The walk ran out of time | Raise QAREN_WALK_SECONDS, or split the plan |
CANDIDATE_DRIFTED | The working tree changed during the run | Re-run against an unchanged checkout |
The screen layer’s own codes appear at the start of failure.detail or in the report, not in
failure.code:
| Screen code | Meaning |
|---|---|
TARGET_AMBIGUOUS | A quoted target, or a phrase target’s scrolled-out name matches, matched two or more elements; each candidate is listed by kind, testID and frame. Use a unique testID or label. |
TARGET_NOT_FOUND | A target did not resolve on screen |
CHECK_UNSURE | A literal check could not be decided from a fresh capture |
VISIBILITY_UNSURE | A wait ended with the target’s visibility still unsure |
SCREEN_EVIDENCE_INCOMPLETE | The captured screen was not complete enough to act on safely |
APP_PROCESS_CHANGED | On iOS, the app crashed or restarted between captures |
CDP_NOT_CONNECTED | The app’s JavaScript runtime did not attach in time, or a target wait made no progress past deadlines.attach_seconds; the detail names the stalled boundary, app liveness, bundle request and host load |
REACT_COVERAGE_LOST | The JS/React connection remained lost at the end of an otherwise passing walk; the walk saves no new blocks. See the React coverage contract |
Teardown, cleanup and publish
Section titled “Teardown, cleanup and publish”| Code | What happened | What to do |
|---|---|---|
CLEANUP_INCOMPLETE | qaren cleanup could not resolve some resources | Re-run qaren cleanup <run-id> --json |
OWNERSHIP_UNPROVEN | The run’s processes were not proven gone | Run qaren cleanup <run-id>, then re-run qaren pr |
RUN_CANCELLED | The run was cancelled | Re-run when ready; the cleanup map names anything retained |
PR_UNAVAILABLE | gh could not read the pull request | Check gh auth status and the pull request, then re-run |
Incomplete teardown
Section titled “Incomplete teardown”When a run cannot prove that a process is gone, it keeps the device lease and records what it
kept. A PR worktree it cannot remove stays recorded for qaren cleanup without holding the
lease. The next run on that device refuses DEVICE_BUSY until the lease is
released. Run:
qaren cleanup <run-id> --jsonIt finishes the teardown from the run’s own records and releases the lease once every resource is accounted for. Do not delete locks in the configured namespace to get around it.
Why were my screenshots withheld?
Section titled “Why were my screenshots withheld?”See the authoritative withheld media guide for reason codes, remedies, diagnostic locations and how screenshots and video retain their first cause.