> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot device sessions

> Fix sessions that won't start, apps that start logged out or fail to install, missed targets, and viewer problems.

When in doubt, start with:

```bash
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 `session.before_script`, 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](/devices/session-prep).

## App Starts Logged Out

### Symptoms

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

### Checks

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

## 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

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