# Crashes & Recovery

## The Application Crashed — What Happens Next?

Exaplay 3 includes an **Auto-Heal** system and a **Watchdog Service** that work together to recover automatically from crashes.

### Automatic Recovery Timeline

```
1. Engine crash detected
        ↓
2. Watchdog Service notices heartbeat stopped (within ~10 s)
        ↓
3. Watchdog terminates the hung process (if still in memory)
        ↓
4. Watchdog waits the configured restart delay (default: 5 s)
        ↓
5. Watchdog restarts Exaplay with -autoheal-restore flag
        ↓
6. Exaplay reads autoheal_state.json and resumes playback
        at approximately the timecode where it stopped
```

If Auto-Heal is properly configured, the black screen should last **10–20 seconds** before playback resumes automatically.

***

## Checking the Watchdog Service Status

If recovery did not happen, verify the Watchdog Service is running:

```powershell
# Check status
Get-Service -Name "Exaplay3Watchdog"

# Start it if stopped
Start-Service -Name "Exaplay3Watchdog"

# Restart it
Restart-Service -Name "Exaplay3Watchdog"
```

Or via **Services** (`services.msc`) — look for **Exaplay 3 Watchdog**.

***

## Manual Recovery After a Crash

If automatic recovery fails, or if you want to restart manually:

1. Check the system tray — the Exaplay icon may still be present (zombie process).
2. Right-click the tray icon and choose **Exit**, or kill the process in Task Manager.
3. Restart Exaplay normally. If Auto-Heal state exists, it will offer to restore playback.
4. To ignore the auto-heal state and start fresh, use the `-fresh` flag:

   ```
   exaplay3.exe -fresh
   ```

***

## Reading the Crash Log

The engine log is at:

```
Documents\Exaplay3\logs\exaplay3.log
```

Useful sections to look for:

| Log entry                         | Meaning                                       |
| --------------------------------- | --------------------------------------------- |
| `[ERROR] GL_OUT_OF_MEMORY`        | VRAM exhausted — reduce media load            |
| `[ERROR] Failed to open media`    | A media file is corrupt or inaccessible       |
| `[CRASH] Access violation at 0x…` | Unexpected C++ exception — share with support |
| `[WATCHDOG] Restart triggered`    | Watchdog detected the crash and restarted     |
| `[AUTOHEAL] State restored`       | Auto-Heal successfully resumed playback       |

***

## Auto-Heal State File

The state file at `Documents\Exaplay3\autoheal_state.json` shows what Exaplay was doing when it crashed:

```json
{
  "project.path": "C:\\Shows\\Festival.vpp",
  "project.name": "Festival",
  "playback.active": true,
  "playback.composition": "Main",
  "playback.time": 125.45,
  "playback.cue-index": 3,
  "playback.cue-time": 45.20,
  "timestamp": "2026-02-20T22:14:33Z"
}
```

* `playback.time` — the timecode (in seconds) when the crash occurred
* `timestamp` — when the state was last saved (should be within the last 2–5 seconds of uptime)

***

## Repeated Crashes

If Exaplay crashes repeatedly (more than 3 times within 5 minutes), the Watchdog stops auto-restarting to prevent a restart loop. This is the **Max Restarts** safety limit.

To investigate repeated crashes:

1. Review the engine log for patterns — do crashes always happen at the same timecode, or when a specific clip plays?
2. Try loading the project with `exaplay3.exe -fresh` (skips auto-heal restore).
3. Try disabling frame blending on clips near the crash timecode.
4. Update the GPU driver — many GL crashes are caused by outdated drivers.
5. If the crash is consistently reproducible, report it with the log and project file.

***

## Disabling Auto-Heal Temporarily

To start Exaplay without restoring the last auto-heal state:

```
exaplay3.exe -fresh
```

This does not disable Auto-Heal for the session — it will continue saving state. It only skips the restore of the *previous* state.

To disable Auto-Heal entirely for a session:

1. Open **Settings → Auto-Heal**.
2. Set **Enable Auto-Heal** to OFF.

> **Warning:** Disabling Auto-Heal means crashes will not be recovered automatically. Only disable for debugging purposes.

***

## Reporting a Crash

When reporting a crash to support, include:

1. The **engine log** (`Documents\Exaplay3\logs\exaplay3.log`)
2. The **autoheal\_state.json** file
3. Windows **Event Viewer** → Application log entries around the crash time
4. Exaplay version (burger menu → About)
5. GPU driver version (Device Manager → Display Adapters)
6. Steps to reproduce the crash (if known)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.exaplay.one/v3/troubleshooting/crashes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.