Troubleshooting

Lidarr will not connect

Use the URL that Aurral can reach. Do not use the browser URL.
If both containers share a Docker network, the URL is often http://lidarr:8686.
Make sure that the Lidarr API key is correct.

Discover is empty

Make sure that Aurral can connect to Lidarr.
Make sure that Lidarr contains artists.
Add a Last.fm API key for better discovery.
Set your listening-history provider in Profile (Last.fm or ListenBrainz username, or Koito instance URL).
Run a manual refresh from Settings > Discover.

Playlists do not download

Configure one or more download sources. Use Settings > Download Clients or Settings > Indexers.
For yt-dlp, select Test connection.
Make sure that the host has yt-dlp and ffmpeg. The Docker image includes both programs.
For slskd, check the connection and the Soulseek login status.
For Usenet, enable the Prowlarr indexers.
Make sure that the Usenet client can reach completed files.
If FLAC matches are scarce, disable Strict format only on the slskd card.
You can also set the preferred format to MP3.
Check job states on the Playlists page and History.

Files do not appear in Navidrome

Make sure that Aurral mounts the same media root as Lidarr (Filesystem and mounts).
Make sure that Settings > Download Clients > Downloads Folder > Path is under that mount.
In Settings > Playback > Navidrome, test and save the Navidrome connection.
Make sure that Navidrome scans Aurral’s downloads path and not only Lidarr’s library.
Aurral’s Aurral Playlists library can be empty until a flow finishes a download. Check for a file under aurral-weekly-flow, then wait for the Navidrome scan.
If the library is missing, check that the Navidrome account can manage libraries through its API.
Review the Navidrome missing-track setting.

Library reuse or download handoff fails on Windows

Symptoms can include the message Lidarr track exists but file is not accessible from Aurral.

Completed slskd or Usenet files can also remain in their source folders. Test library access can fail while Lidarr is operational.

Mount the same parent host folder that Lidarr uses into Aurral.
Do not use separate mounts for the library and downloads.
For example, use N:/ServerFolders/Music:/music.
Set Downloads Folder > Path under that mount, for example, /music/Aurral.
After you change Compose volumes or environment, recreate the container: docker compose up -d --force-recreate.
Run Settings > Lidarr > Test library access to see the exact path Aurral cannot read.
If necessary, set PATH_MAPPINGS=N:/ServerFolders/Music|/music in the Compose file.
You can also add mappings under Settings > Download Clients > Remote Path Mappings.
For NZBGet on Windows, open Settings > Download Clients > NZBGet.
Set Completed download path if Aurral cannot detect the folder automatically.

See Filesystem and mounts: Windows and mixed Docker setups.

Library access fails on a folder that is not your root folder

Test library access and Storage health can fail on a sample track whose path sits outside every Lidarr root folder, even though the root folder itself passes.

Lidarr keeps each artist’s own folder when you change or rename a root folder, so artists stay at the old location.

Compare the failing path with Root folder in Lidarr in the same check.
If the failing path is outside it, open that artist in Lidarr, select Edit, and move the files into the current root folder.
Otherwise, add the old location as a Lidarr root folder and mount it into Aurral.

Navidrome playlists show but tracks will not play

Flows or shared playlists can appear in Navidrome, but the tracks do not play.

The path problem is common when Aurral runs in Docker and Navidrome runs on Windows.

Make sure that Test library access passes in Lidarr settings.
Enable Use Navidrome paths in M3U files and add a Navidrome path mapping in Settings > Playback > Navidrome.
Alternatively, set M3U_PATH_MODE=remote and M3U_PATH_MAPPINGS in the Compose file.
Recreate the container.
Refresh the playlists to rewrite the .m3u files.
Run or save a flow. You can also edit and save a shared playlist.
Open a generated .m3u under aurral-weekly-flow. Make sure that track lines use paths Navidrome can open.

Leave Use Navidrome paths in M3U files off when Navidrome runs in Docker with the same mounts as Aurral.

See Navidrome: Different Navidrome paths.

Plex playlists are empty or tracks are missing

Sync to Plex now can succeed while the playlists have no tracks. The Aurral library can also stay empty after a scan.

Make sure that Plex can read the flow download tree.
The Plex container or host must contain this path: <downloads>/aurral-weekly-flow/<flow-id>/....
If Plex and Aurral use different mounts, set Settings > Playback > Plex > Plex Aurral Library path to the folder that Plex sees.
Leave Plex Aurral Library path blank if both apps use the same path prefix.
Save the settings.
Select Sync to Plex now again.
Initial scans can take several minutes. Aurral runs catch-up synchronization in the background while Plex indexes files.
Make sure that flows finish their downloads before you expect Plex playlists to populate.
Use Navidrome paths in M3U files does not apply to Plex.

See Plex integration.

Make sure that AUTH_PROXY_TRUSTED_IPS matches the source address of your reverse proxy.
This value is different from TRUST_PROXY. Use the proxy access logs to find its source address.
If you enable proxy authentication, set AUTH_PROXY_TRUSTED_IPS before you expose the app.
Reload the page. Aurral shows its sign-in page when the browser holds no valid session, and a reload lets your proxy authenticate again.
Page loads always reach your proxy, and an open tab reloads itself when the proxy rejects an API call, so ending the identity-provider session no longer needs a manual hard refresh.
If errors such as “Error Loading Artist” persist instead, your proxy is answering rejected API calls with an Aurral-shaped JSON error. Let it return its own redirect or 401.
For Authelia or forwardAuth, set AUTH_PROXY_DOMAIN to your authentication origin.
For Authentik, curl -i https://your-aurral-host/outpost.goauthentik.io/ping must return 204.
If it returns Aurral HTML, route /outpost.goauthentik.io directly to the Authentik outpost.
Use the same correction if it returns another authentication redirect.
Do not apply auth_request to that route.
If Authentik logout returns to Aurral’s login page, check the logout variable.
Use the exact variable name AUTH_PROXY_LOGOUT_URL.
Set its value to https://your-aurral-host/outpost.goauthentik.io/sign_out.
If the Log out control is missing, that variable is unset. Aurral hides the control when it cannot end the proxy session.
This problem affects only proxy-auth setups that use AUTH_PROXY_ENABLED or AUTH_PROXY_HEADER. It does not affect local password login.

Docker memory looks high after you view cover art

Official images preload jemalloc. This lets sharp return free native memory after it optimizes cover art.

Aurral fetches covers on demand without a background prefetch. It caches each cover as a card-size WebP image (512px).

The image-proxy disk cache has a 256MB limit and uses least-recently-used removal. Restart Aurral if you need a clean memory baseline.

Permission errors

Make sure mounted folders are writable by the container user.
Set PUID and PGID to match your host folder owner. Follow Servarr’s Docker Guide for shared-group setups.

Need more logs

Set AURRAL_VERBOSE_LOGS=true.
Restart Aurral.
Check the container logs.