mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# 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. |