Guides
Troubleshooting
Fixes for a locked library, a stopped service, playback errors and missing tools.
“Library is locked”
The daemon found library.db but not a key that opens it. Enter your 24-word recovery phrase on the lock screen. Nuvo never replaces an existing database, so your data is safe until you unlock it.
Causes: the keyring was reset, you moved to a new user account, or the keyring is not running.
If you lost the phrase and the key is gone, the library cannot be opened. Restore a copy that you still have the phrase for. See backup.
Waiting at start
On start, Nuvo waits for the keyring. A keyring unlock prompt can appear behind the window. Nuvo waits up to two minutes for it.
“Library service stopped”
The daemon crashed four times within a minute and Nuvo gave up. Restart Nuvo. If it repeats, read the log at ~/.local/state/nuvo/core.log and open an issue with the support report from Settings, Network.
A single crash is handled for you: Nuvo restarts the service within a few seconds and playback continues.
Another daemon is running
The message “another nuvo-core is already running” means a daemon already answers on the socket. Close the other Nuvo instance. A stale socket file from a crash is replaced automatically.
A track will not play
- Run the network check (Settings, Network). See network and proxy.
- Sign in to YouTube in Settings, YouTube. Signing in prevents blocked streams.
- Check the dependencies: the dependency check marks
yt-dlpas outdated after 90 days and reports it when it is missing. - Try again. Nuvo falls back to another source for the same song when one fails.
SoundCloud tracks can be unplayable for reasons the player shows, such as a region block.
Local file will not play
Files in a codec the player cannot decode, for example ALAC, are listed with the reason. A liked track plays its streamed match instead.
Pasted link does nothing
- Spotify links are not read. Import a CSV instead.
- TikTok and recognition need
yt-dlpandffmpeg. Settings shows what is missing. Install them, then press Check again. - Recognition from system audio needs ffmpeg with PulseAudio input.
yt-dlpneeds a JavaScript runtime (deno,nodeorbun) to solve YouTube’s challenges.
No Notch
GNOME on Wayland cannot pin a window. Use the system media widget. See tray and Notch.
No tray icon
The tray needs a StatusNotifier watcher. On GNOME install the AppIndicator extension.
The look is broken
Hold Shift while starting Nuvo, or use --safe-appearance. See themes and custom CSS.
Slow or large cache
Settings, Cache and Storage shows usage and lets you set a limit or clear the cache. See audio cache.
Where the log is
~/.local/state/nuvo/core.log. It records routes and timings, not track ids.