documentation/resources/troubleshooting.md

Troubleshooting & Diagnostics

Step-by-step diagnostic workflows and resolutions for common issues across Vyla Home, Vyla Go, Vyla TV, Stream API, and the SDK.

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.
  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:

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:

& "$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:

& "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" logcat -d | Select-String "VylaGo|AndroidRuntime|FATAL"

3. Resetting Cached App Data

& "$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:

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.