How it works
Troubleshooting
The refusals and failures you meet most, and what to do about each.
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 the receipt's artifacts.report path shows each walked line.
Refusals exit 4 and mean the run could not start or could not decide; failures exit 1.
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 |
PNPM_PROCESS_GROUP_UNSUPPORTED | A completed pnpm exec probe did not prove process-group preservation | Follow the launcher compatibility contract and the pnpm-source row in qaren doctor |
PNPM_PROBE_TIMED_OUT | The pnpm exec probe timed out on every attempt within the dependency-install budget; the launcher was not judged | Re-run when the machine is less loaded, or run qaren doctor; failure.detail lists the attempts |
GITHUB_AUTH_UNAVAILABLE | PR lookup could not use GitHub authentication | Follow the GitHub authentication contract |
DISK_BUDGET_EXCEEDED | Under 1 GiB free for the run storage root or the app, or under about 10 GiB for a clean iOS build | Free space on the volume failure.detail names, then re-run |
Development target admission
For DEV_TARGET_MISSING or admission-time CORE_REFUSED, follow the receipt's
next_action and recovery rungs using the authoritative
admission and recovery contract.
Development overlays before step 1
For CORE_REFUSED with a DEV_MENU_HIDE_UNVERIFIED_* inner code in
failure.detail, follow failure.next_action and the authoritative
overlay clearance and recovery contract.
Devices
For BUILD_FAILED with cause=toolchain-newer-than-prebuilt, follow the
receipt's next action and the
native build recovery contract.
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 |
WATCHMAN_VOLUME_STALLED | Watchman reported a cookie-sync timeout | Follow next_action; see the launch readiness contract for bounds, diagnostics and recovery |
MANIFEST_NOT_WARM | Dev-client manifest warm-up refused before launch; an unpinned fingerprint runtimeVersion policy can cause per-request fingerprint recomputation | Follow next_action; see the launch readiness contract for pin states, bounds and recovery |
LANE_NOT_WARM | The owned simulator failed the warm-lane contract | Follow next_action and failure.detail; use the linked contract for settings, first-screen requirements and doctor diagnostics |
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 | Follow next_action and the screen evidence contract for target diagnostics and repeat guidance |
CORE_REFUSED | The screen layer refused; the detail starts with its own code | Resolve that refusal, then re-run |
PRESS_NOT_REGISTERED | The selection effect could not be verified | Follow the press evidence contract |
BLOCK_START_MISSING | The block's declared start was absent; this is a typed refusal with exit code 4 | Follow the saved-block contract |
DEV_REDBOX | A development error overlay prevented safe progress; exit code 4 | Follow next_action and the step recovery contract for platform coverage, dismissal bounds and causes |
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; interpret the latest controls and suggested edit using the screen evidence contract. |
TARGET_NOT_FOUND | A target did not resolve on screen |
TARGET_NOT_FOUND_AFTER_LAUNCH | The launch target wait expired; follow the step recovery contract for eligibility, bounds and the suggested plan edit |
TARGET_REACT_ONLY | A quoted wait repeatedly found only a React-mounted match without native visibility; follow the wait evidence and recovery contract for diagnostic fields, iOS scroll recovery and next steps |
TARGET_WAIT_TIMEOUT | A wait's first capture did not complete; follow the wait evidence and recovery contract for deadline details and next steps |
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 | Runtime attachment or readiness could not be established; see the admission and recovery contract for typed causes, deadlines and diagnostic fields |
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
| Code | What happened | What to do |
|---|---|---|
CLEANUP_INCOMPLETE | qaren cleanup could not resolve some resources | Follow the receipt's next_action and the cleanup contract |
OWNERSHIP_UNPROVEN | The run's processes were not proven gone | Follow the receipt's next_action and the cleanup contract |
RUN_CANCELLED | The run was cancelled | Re-run when ready; the cleanup map names anything retained |
PR_UNAVAILABLE | Pull request lookup, comment creation or label edit failed; failed qaren pr lookups also check authentication | Follow the GitHub authentication contract |
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. For dead-holder reclamation and intentional inspection holds, see the
iOS admission and cleanup contract.
To request cleanup explicitly, run:
qaren cleanup <run-id> --json
It resumes teardown from the run's own records. If it refuses, follow the receipt's
next_action; see the authoritative
cleanup contract
for recorded iOS runner recovery and lease-release requirements. Do not delete locks
to get around a refusal.
Why were my screenshots withheld?
See the authoritative withheld media guide for reason codes, remedies, diagnostic locations and screenshot and video cause selection.