Troubleshooting

revyl device doctor

​

Session Won’t Start

​

Symptoms

• revyl device start fails or hangs.
• revyl device info says no active session.

​

Checks

1. Confirm auth: revyl auth status
2. Confirm active sessions: revyl device list
3. Retry with explicit platform: revyl device start --platform ios
4. If the project uses before_session, confirm you are in (or under) the directory that owns .revyl/config.yaml, the script is executable, and it exits 0. A mint failure aborts start before the device boots — see Auth And Session Prep.

​

App Starts Logged Out

​

Symptoms

• Session boots, but the app shows a sign-in screen instead of the authenticated state your auth_bypass config should produce.

​

Checks

1. Confirm cwd resolves the project that declares before_session / auth_bypass (monorepo: cd into the app directory that owns .revyl/).
2. Re-run start so before_session remints; launch env is fixed at boot.
3. If you rely on org launch variables only (no before_session), refresh those tokens — they expire independently of the session.
4. Deep-link placeholders must come entirely from before_session or entirely from org vars; a mix fails at setup. Full contract: Auth Bypass Deep Links.

​

App Install or Launch Fails

​

Symptoms

• install fails for app URL.
• launch fails with bundle ID errors.

​

Checks

1. Verify build URL is reachable and points to APK/IPA.
2. Re-run install and read returned bundle ID.
3. Launch with exact bundle ID returned by install.

​

Grounded Target Misses

​

Symptoms

• tap --target hits wrong location.
• type --target focuses wrong field.

​

Fixes

1. Re-observe current UI: revyl device screenshot --out debug.png
2. Use visible text in target: --target "the 'Sign In' button"
3. If needed, fall back to raw coordinates (--x, --y) for this step.

​

Actions Stop Working Mid-run

​

Symptoms

• Commands begin failing after earlier success.
• Session seems stale.

​

Fixes

1. Confirm the session is still active: revyl device list
2. Switch explicitly: revyl device use <index>
3. If timed out, start a new session and continue.

​

Screenshot or Viewer Issues

​

Symptoms

• Screenshot command fails.
• Live viewer appears frozen.

​

Fixes

1. Run revyl device info and confirm viewer_url.
2. Re-run revyl device screenshot --out current.png.
3. Stop and restart session if the device session became unhealthy.

​

Quick Recovery Sequence

revyl auth status
revyl device list
revyl device doctor
revyl device stop --all
revyl device start --platform ios