# Troubleshooting & Diagnostics

<p class="page-description">Step-by-step diagnostic workflows and resolutions for common issues across Vyla Home, Vyla Go, Vyla TV, Stream API, and the SDK.</p>

## Desktop: Vyla Home

### 1. Windows: "WebView2 runtime initialization error"
- **Cause**: The Microsoft Edge WebView2 runtime is missing or corrupted on the host machine.
- **Resolution**:
  1. Download and run the Evergreen Bootstrapper installer from [Microsoft's WebView2 page](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
  2. If using portable builds, verify that `WebView2Loader.dll` exists in `bin\WebView2Loader.dll`.

### 2. Windows: "OS Error 32: File in use by another process"
- **Cause**: A previous Tauri, Node.js, or Cargo process is still running in the background and holding a file lock.
- **Resolution**: Terminate any dangling processes in PowerShell:
  
```powershell
Stop-Process -Name "vyla-home", "node", "cargo" -Force -ErrorAction SilentlyContinue
```

### 3. Linux: Build Fails with Missing WebKit or AppIndicator
- **Cause**: Linux requires native GTK3 and WebKit development headers.
- **Resolution**: Install required system packages:
  - **Fedora**: `sudo dnf install webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel`
  - **Ubuntu/Debian**: `sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev`

### 4. Inspecting Node Sidecar Logs
If Vyla Home launches but media fails to resolve:
- **Windows**: Open `%APPDATA%\vyla-home\vyla-home-files\logs\node-debug.log`
- **macOS**: Open `~/Library/Application Support/vyla-home/vyla-home-files/logs/node-debug.log`

---

## Mobile: Vyla Go

### 1. Emulator DNS Timeouts when Connecting to GitLab
- **Cause**: Android emulators occasionally fail to resolve remote domains when private DNS is active.
- **Resolution**: Disable private DNS mode via ADB:
  
```powershell
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"
shell settings put global private_dns_mode off
```

### 2. Dumping Crash Logs from Device
To capture a full logcat dump of crash traces:
```powershell
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -d | Select-String "VylaGo|AndroidRuntime|FATAL"
```

### 3. Resetting Cached App Data
```powershell
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell am force-stop com.vyla.go
& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" shell pm clear com.vyla.go
```

---

## Living Room: Vyla TV

### 1. Build Fails during `assembleDebug`
- **Cause**: Incompatible Java Development Kit (JDK) or missing Android TV SDK platform.
- **Resolution**:
  1. Ensure JDK 17 or JDK 21 is active: `java -version`.
  2. Ensure Android TV API level 26 or higher is installed via Android Studio SDK Manager.

### 2. Video Stalls or Fails to Play on Fire TV
- **Cause**: Hardware codec mismatch or network buffer underrun.
- **Resolution**:
  1. Inside the player, press the Down button on your D-pad to open the stream switcher.
  2. Select an alternative provider (e.g. switch from an adaptive HLS stream to a direct 1080p stream).

---

## Backend: Stream API

### 1. SSE Events Delayed or Arriving All at Once
- **Cause**: The reverse proxy (Nginx, Cloudflare, Caddy) is buffering chunked responses.
- **Resolution**:
  1. In Nginx, ensure `proxy_buffering off;` and `proxy_cache off;` are configured in your `location` block.
  2. In Cloudflare, ensure response buffering is disabled for your streaming subdomain.

### 2. `EADDRINUSE: address already in use :::7860`
- **Cause**: A previous Stream API instance is already bound to port 7860.
- **Resolution**:
  
```bash
lsof -i :7860
kill -9 <PID>
```

### 3. TMDB API Warnings in Console
- **Warning**: `Warning: TMDB_API_KEY not set, imdb-required sources will be unavailable`
- **Resolution**: Add `TMDB_API_KEY=your_key` to your `.env` file and restart the service.