Troubleshooting

Start with Settings > Storage health > Run checks. Most file problems show up there with the exact path and a suggested fix.

Lidarr does not connect

Use a URL that the Aurral server can reach, not the URL in your browser.
If both containers share a Docker network, the URL is often http://lidarr:8686.
Make sure that the Lidarr API key is correct.
Make sure that Enabled is on in Settings > Lidarr.

Discover is empty

Make sure that your Library has artists, or that you have listening history. Aurral picks seed artists from both.
Set your listening-history provider in Profile > Listening history.
Without a Last.fm API key, Aurral finds similar artists only for seed artists that ListenBrainz knows. Adding a key in Settings > Connect > Last.fm often fills an empty list.
If the status next to the Discover title shows a refresh step, wait a minute. Each user’s first set takes about as long as a few dozen ListenBrainz or Last.fm requests.
Start a refresh in Settings > Discover. It refreshes trending artists and then rebuilds every user’s recommendations. Discover and Settings > Discover keep showing the refresh until your own recommendations are rebuilt, and they show Refresh failed if it stops.

Playlists do not download

Configure one or more download sources in Settings > Download clients. For Usenet, also configure Settings > Indexers.
For yt-dlp, select Test connection. Outside Docker, make sure that the host has yt-dlp and ffmpeg. The Docker image includes both.
For slskd, check the connection and the Soulseek sign-in status.
For Usenet, turn on the Prowlarr indexers, and make sure that Aurral can read the completed files.
If few FLAC files are found, turn on MP3 or M4A tiers in Settings > Download clients > Quality profile.
Make sure that the cutoff and the tier order match the quality that you want.
Check the job states on the playlist page and in Activity.
For a single track that keeps failing, choose the download yourself. See Choose a download yourself.

Removed playlist tracks still appear in Activity

Aurral deletes playlists and flows in the background. The page shows removal queued until the work finishes.

If a download client still shows work after the removal, check that client’s queue. Aurral does not import results into the removed playlist. If Aurral cannot remove the item from the client, the removal fails and Aurral tries again.

Lidarr is unreachable

When Lidarr fails several requests in a row, Aurral pauses Lidarr requests, and Settings > Lidarr says that Lidarr is unreachable. Lidarr’s music stays in the Library, and Aurral does not take over Lidarr’s artists and albums.

Check that Lidarr is running and that the Aurral server can reach the Server URL.
In Settings > Lidarr, select Test connection.

Do not turn off Enabled to fix an outage. Turning Lidarr off removes its music from the Library. See Turning Lidarr off.

Lidarr’s music disappeared from the Library

Aurral removes Lidarr’s music when Settings > Lidarr > Enabled is off or the API key is empty. Turn Lidarr on, enter the API key, and save. Aurral scans the Lidarr root folders again.

Albums are missing from the Library

When Lidarr is connected, Settings > Lidarr > Show available music only is on by default. It hides albums without downloaded files, including albums that Aurral is still downloading. Turn it off to see them, or follow the download on the album page and in Activity. Without Lidarr, the Library shows every album that you add.

Settings warn that roots overlap

Aurral shows this warning when the Downloads Folder and a Lidarr root folder are the same folder, or when one is inside the other. The check applies your Lidarr remote path mappings. Aurral allows the overlap, but Lidarr can rename, import, or delete files under its root folders.

While the folders overlap, Aurral treats files in a Lidarr root folder as Lidarr’s and never deletes them. A Lidarr root folder inside the Downloads Folder is scanned only as Lidarr’s. Aurral never moves files to remove the overlap.

To clear the warning, set Settings > Download clients > Downloads Folder > Path to a folder outside every Lidarr root folder. Move the existing files yourself if you want them in the new folder.

Browse folders does not show my media folder

By default, Browse folders opens only /data, the app data folder, and the Downloads Folder. If your media mount is at another path, such as /music, set FILE_BROWSE_ROOTS=/music and recreate the container. See Environment variables.

Files do not appear in Navidrome

Make sure that Settings > Download clients > Downloads Folder > Path is under the shared media mount.
If you use Lidarr, make sure that Aurral mounts the same media root as Lidarr. See Filesystem and mounts.
In Settings > Playback > Navidrome, test the connection.
Make sure that Navidrome scans the Downloads Folder, not only the Lidarr library.
The Aurral Playlists library stays empty until the first download finishes. Check for a file in the Downloads Folder or under _flows, then wait for the Navidrome scan.
If the library is missing, make sure that the Navidrome account can manage libraries through the API.
Read about removing missing tracks in Navidrome.

Library reuse or download import fails on Windows

The log can show Lidarr track exists but file is not accessible from Aurral. Completed slskd or Usenet files can also stay in their download folders. The Lidarr library storage check can fail while Lidarr itself works.

Mount the parent host folder that Lidarr uses into Aurral, for example N:/ServerFolders/Music:/music. Do not use separate mounts for the library and the downloads.
Set Downloads Folder > Path under that mount, for example /music/Aurral.
Set FILE_BROWSE_ROOTS=/music, so that Browse folders can open the mount.
After you change volumes or environment in the Compose file, recreate the container: docker compose up -d --force-recreate.
Run Settings > Storage health > Run checks. The Lidarr library section shows the exact path that Aurral cannot read.
If necessary, add a mapping in Settings > Download clients > Remote path mappings, or set PATH_MAPPINGS=N:/ServerFolders/Music|/music.
For NZBGet on Windows, open Settings > Download clients > NZBGet. If Aurral cannot find the finished downloads, set Completed download path.

See Windows and mixed Docker setups.

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

The Lidarr library storage check can fail on a sample track outside every Lidarr root folder, while the root folder itself passes. When you change or rename a root folder in Lidarr, Lidarr leaves each artist folder where it was.

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

Navidrome playlists appear, but tracks do not play

First, wait for Navidrome to finish its scan. Aurral adds tracks to a Navidrome playlist only after Navidrome indexes them.

Make sure that the Lidarr library storage check passes.
Make sure that Navidrome scans the Downloads Folder and each Lidarr folder that playlists reuse.
Make sure that the Downloads Folder has the same absolute path in both containers.
Run a flow, or edit and save a static playlist.
Run a full Navidrome scan and wait for Aurral’s next update.

See Navidrome: Filesystem 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 while Plex scans.

Make sure that Plex can read the Downloads Folder, including <downloads>/Artist/Album/Track and <downloads>/_flows/<flow-id>/....
If Plex and Aurral use different paths, set Settings > Playback > Plex > Plex Aurral Library path to the folder that Plex sees. If they use the same path, leave it blank.
Wait for the Plex settings to save, then select Sync to Plex now again.
Wait for the first scan. It can take several minutes. Aurral runs catch-up syncs while Plex indexes files.
Make sure that the flow finished its downloads.
For another user’s playlists, make sure that the user linked a Plex account.

See Plex.

Sign in with a local Aurral account. The instance API key does not work for Subsonic.
If the client reports Token authentication failed, switch it to password authentication. In Music Assistant, turn on legacy authentication. In Feishin, set LEGACY_AUTHENTICATION=true.
An account created before Aurral stored Subsonic credentials needs one Aurral sign-in, or a password reset by an admin.
An account created by OIDC or a reverse proxy needs a local password first.

See Navidrome and Subsonic.

Google and Plex sign-in work only for accounts that already linked them. Sign in another way, then link the account in Profile > Connected accounts or Profile > Plex account. See Sign in with Google or Plex.

This section applies only when AUTH_PROXY_ENABLED or AUTH_PROXY_HEADER is set. It does not affect local password sign-in.

Make sure that AUTH_PROXY_TRUSTED_IPS matches the address that your reverse proxy connects from. Find it in the proxy access logs. This value is different from TRUST_PROXY.
Set AUTH_PROXY_TRUSTED_IPS before you expose Aurral.
Reload the page. Aurral shows its sign-in page when the browser has no valid session. A reload lets your proxy authenticate again.
A short backend restart does not sign out an open tab. If the log repeats WebSocket server initialized and Server running, the backend keeps restarting. Check the container or the file-watcher process.
If an error such as “Error loading artist” stays on the page, your proxy answers rejected API calls with a JSON error in Aurral’s format. Let the proxy return its own redirect or 401 instead.
For Authelia or another forward-auth proxy, set AUTH_PROXY_DOMAIN to your sign-in address.
For Authentik, curl -i https://your-aurral-host/outpost.goauthentik.io/ping must return 204. If it returns Aurral HTML or another sign-in redirect, route /outpost.goauthentik.io directly to the Authentik outpost. Do not apply auth_request to that route.
If an Authentik logout returns to Aurral’s sign-in page, set AUTH_PROXY_LOGOUT_URL=https://your-aurral-host/outpost.goauthentik.io/sign_out. Check the spelling of the variable name.
If Log out is missing, AUTH_PROXY_LOGOUT_URL is not set. Aurral hides Log out when it cannot end the proxy session.

Docker memory rises while tasks run

Library scans, discovery refreshes, playlist downloads, and other tasks run in their own background processes. Aurral starts each process when it has work and stops it about a minute after the work finishes, so docker stats rises during tasks and falls back when Aurral is idle. Settings > Tasks shows a stopped process as Standby.

Docker memory looks high after you view cover art

The official image preloads jemalloc, so Sharp returns free memory to the system after it processes cover art.

The web app loads artwork directly from the provider links, and the browser caches it. Subsonic clients that need Aurral to serve artwork get covers on demand. Aurral caches these as 512 px WebP images.

The artwork disk cache holds up to 256 MB and removes the least recently used images first. To start from a clean memory baseline, restart Aurral.

Aurral stores artwork links in SQLite, separately from the cached image files. When the cache removes an image, Aurral can fetch it again without a new metadata lookup.

Clear artwork cache in Settings > Discover removes the stored links and the cached image files. It keeps your recommendations. Aurral rebuilds the artwork when it needs it.

The container exits with code 137

Exit code 137 means that the container received SIGKILL. Check whether Docker stopped it for using too much memory:

docker inspect <container> --format 'oom={{.State.OOMKilled}} memory_limit={{.HostConfig.Memory}}'

If the container still runs, check its current memory use:

docker stats --no-stream <container>

docker stats has no data for a stopped container. Use the docker inspect result and the host’s out-of-memory logs instead.

If oom=true, increase the memory limit of the container.
If oom=false, check the container supervisor and the Docker daemon logs for the process that sent SIGKILL.

Permission errors

Make sure that the container user can write to the mounted folders.
Set PUID and PGID to the owner of the host folders. For shared groups, follow the Servarr Docker Guide.

Get more logs

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

Roll back after the release metadata worker was introduced

Stop Aurral before restoring a version that has no separate release metadata worker. Using the current version, run the maintenance command against the same application data directory:

AURRAL_DATA_DIR=/path/to/config node backend/scripts/restoreReleaseMetadataQueue.js

For Docker, run the command in a temporary container using the current image and the same config volume. Keep the regular Aurral container stopped. Preserve a custom AURRAL_DB_PATH if your installation uses one.

The command moves pending refreshes and their schedule to the legacy system queue. It preserves job ids, retry counts, deadlines, and the next scheduled refresh. It refuses to run while a metadata job is still claimed. Let the current version finish those jobs, then stop it and retry the command before starting the older version. If Aurral stopped during a refresh, the command returns that refresh to the queue once its claim expires, which can take up to an hour.