Skip to content

Troubleshooting

Jump to bottom
blarns edited this page Jun 3, 2026 · 1 revision

Troubleshooting

App won't launch

"libVLC not found" / VLC errors on startup

Make sure libvlc-dev and vlc are installed:

# Ubuntu/Debian/Mint
sudo apt install libvlc-dev vlc libavcodec-extra

If VLC is installed in a non-standard location, set the path explicitly:

export VLC_LIB_PATH=/usr/lib/x86_64-linux-gnu/libvlc.so
./gradlew composeApp:run

Out of memory during build

export GRADLE_OPTS="-Xmx2g"
./gradlew composeApp:run

"Resource nuvio-icon.png not found" crash

This should be fixed in current versions. If you see it, do a clean build:

./gradlew clean composeApp:run

Authentication

Can't log in / authentication fails

Ensure local.properties exists in the project root and contains valid Supabase credentials. See Configuration.

Trakt OAuth doesn't complete

The Trakt OAuth flow uses a localhost redirect. Make sure nothing else is occupying the redirect port. Try restarting the app and attempting authentication again.

Video playback

Black screen / no video

  1. Check VLC is working independently: vlc <stream-url>
  2. Try disabling hardware acceleration: Settings → Playback → Linux desktop → Hardware video acceleration → off, then restart the app.
  3. If using NVIDIA, ensure nvidia-vaapi-driver is installed and up to date.

Graphical glitches / corrupted video

Disable VA-API (Settings → Playback → Linux desktop → Hardware video acceleration → off) and restart. If that fixes it, your VA-API driver has a compatibility issue with this content type.

Poor performance / high CPU usage

Enable hardware acceleration if it's not already on. For 4K or HEVC content, hardware decoding moves the decode load off the CPU onto the GPU media engine.

Audio

No sound

  1. Try changing the audio output: Settings → Playback → Linux desktop → Audio output → PulseAudio (or ALSA if you're not using PulseAudio). Restart the app.
  2. Check your system audio output device is set correctly.

Wrong audio device

Select the correct backend in Settings → Playback → Linux desktop → Audio output, then restart.

Media keys / MPRIS2

Media keys not working

  • MPRIS2 requires a D-Bus session bus. This is available on all mainstream desktop environments (GNOME, KDE, XFCE, etc.).
  • Check MPRIS2 is registered: playerctl --list-all — nuvio should appear when the app is running.
  • On minimal setups without a session bus, MPRIS2 silently does nothing — it won't crash the app.

Notifications

Notifications not appearing

Ensure notify-send is installed:

# Test it manually:
notify-send "Test" "Does this appear?"

If the test notification appears but Nuvio's don't, check that notifications are enabled in Settings → Notifications.

Performance

Slow startup

The first run after a code change recompiles. Subsequent launches reuse the compiled classes and are faster. Run in the background if needed:

./gradlew composeApp:run &

High memory usage

The JVM default heap can grow large. Cap it in gradle.properties:

org.gradle.jvmargs=-Xmx2g

Reporting bugs

Please open an issue at github.com/blarns/NuvioForLinux/issues with:

  • Your distro and kernel version
  • GPU and driver version
  • Steps to reproduce
  • Any error output from the terminal

Clone this wiki locally