Troubleshooting

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

Read the log

Open Settings > Status > Logs. Problems groups the warnings and errors from the last day, with how often each happened. Select one to see its lines. Download saves the last day of the log, and Copy problems copies its warnings and errors. Passwords, tokens, and API keys are masked before they are saved, so the log is safe to attach to an issue.

Once you’ve dealt with the problems listed, Start fresh hides them so only new ones show, on this page and in the links an agent reads. Nothing is deleted, and Show earlier brings them back.

To see more detail, turn on Debug logging, reproduce the problem, and turn it off again.

Agent triage copies a prompt for an AI agent with live links to the log and a playbook that helps it tell a setup problem from an Aurral bug, and file an issue when it finds one. Fill in what went wrong after you paste it. When it’s done, it asks whether to start the log fresh for you. The links carry your admin API key, which gives full admin access, so only share them with an agent you trust. Rotate the key in Settings > General to revoke them.

The log lives in the logs folder of the data folder. In Docker that is /config/logs/aurral.log. It holds up to 50 MB, then drops the oldest lines. To download it from another machine, use the API key:

curl -H "X-Api-Key: YOUR_API_KEY" -o aurral-logs.txt \
  "https://aurral.example.com/api/logs/export"

Discover is empty

Make sure that your Library has artists, or that you have listening history. Aurral picks seed artists from both.
Add your listening history in Settings > Listening.
Without a Last.fm API key, Aurral finds similar artists only for seed artists that ListenBrainz knows. Adding a key in Settings > Discovery > 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 > Discovery. It refreshes trending artists and then rebuilds every user’s recommendations. Discover and Settings > Discovery 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 > Downloads. For Usenet, also connect Prowlarr there.
For yt-dlp, select Test connection. Outside Docker, make sure that the host has yt-dlp and ffmpeg. The Docker image includes both.
If yt-dlp fails with “Sign in to confirm you’re not a bot”, give it a cookies file. See YouTube sign-in.
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 AAC tiers in Settings > Downloads > 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.

Albums are missing from the Library

The Library lists albums that have a file you can play, plus albums that Aurral is downloading. Follow a download on the album page and in Activity. Albums of an artist’s discography that you don’t have are on the artist’s Discover page.

An album whose files all went missing from disk leaves the list. If that happened to many albums at once, check the folders in Settings > Status > Storage, then select Refresh in Library.

Browse folders does not show my media folder

By default, Browse folders opens only /data, the app data folder, and the Library 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 or playlists do not appear in a media server

Make sure that Settings > Library > Library folder > Path is under the shared media mount.
Make sure that the media server has the Library folder in a music library.
Check that the playlist file exists in the folder that Settings > Library > Playlist files shows.
Plex gets playlists only when an admin connects it with Send playlists on. See Plex.
Read about removing missing tracks in Navidrome.

Download import fails on Windows

Completed slskd or Usenet files can stay in their download folders while the download client itself works.

Mount the parent host folder that your download clients use into Aurral, for example N:/ServerFolders/Music:/music. Do not use separate mounts for the library and the downloads.
Set Library 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 > Status > Storage > Run checks. A failed check shows the exact path that Aurral cannot read.
If necessary, add a mapping in Settings > Downloads > Remote path mappings, or set PATH_MAPPINGS=N:/ServerFolders/Music|/music.
For NZBGet on Windows, open Settings > Downloads > NZBGet. If Aurral cannot find the finished downloads, set Completed download path.

See Windows and mixed Docker setups.

Playlists appear, but some tracks are missing

Wait for the media server to finish its scan. Jellyfin can take a few minutes.
Make sure that the media server has the Library folder and each read-only folder that playlists use in its music libraries.
Make sure that the server sees the Library folder and the read-only folders at the same paths as Aurral. See Media servers see a different path.

Sign in with a local Aurral account. API keys do 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 sign-in works only for accounts that already linked it. Sign in another way, then link the account in Settings > Profile > Sign-in methods. See Sign in with Google.

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.

Listening history from a media server is missing

Open Settings > Listening and select the server. The page shows the last sync and any error.
For Jellyfin, install the Playback Reporting plugin. It records plays only from the day it is installed.
Select Sync now to import new plays at once. Aurral also checks every hour.

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 > Status > Tasks shows a stopped process as Standby.

A background task restarts after it runs out of memory

Each background process stops when its JavaScript heap reaches 2 GB. The log then shows a line like [BackgroundWorkers] library exited (SIGABRT); running ...; restarting. It names the job that was running and the memory that the process used at its last check, and Aurral starts the process again.

If a large library needs more memory, raise AURRAL_WORKER_MAX_HEAP_MB. See Environment variables.

To capture a heap snapshot for a bug report, create a diagnostics folder in your app data folder, set this variable, and restart Aurral:

environment:
  - NODE_OPTIONS=--heapsnapshot-near-heap-limit=1 --diagnostic-dir=/config/diagnostics

Node then writes one .heapsnapshot file to /config/diagnostics when a process nears its limit. Writing it pauses the process and needs about as much free memory as the heap again, so remove the variable after you have the file.

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.

Library artwork is stored once per album and artist as a 512 px WebP image in the library-artwork folder of the data directory. Aurral makes each copy the first time it is shown, in the web app or a Subsonic client, and serves it from disk after that. A copy is replaced when the album’s files change and removed when the album or artist leaves the Library. When a Subsonic client asks for a smaller size, or the web app shows a playlist cover in a small slot, Aurral resizes the image on request, at most two at a time.

Artwork outside the Library, such as Discover and Search, loads directly from the provider links, and the browser caches it. Fanart.tv and Deezer thumbnails use the smallest size the provider offers for the image’s display size and screen density. Larger artwork uses the original image. If a preview is unavailable, Aurral retries the original before showing the existing fallback.

A separate disk cache holds up to 256 MB of artwork outside the Library that Aurral serves itself, such as covers of playlist tracks you do not have, and removes the least recently used images first. Aurral downloads at most two covers at a time. Sharp does not retain an image-processing cache. To start from a clean memory baseline, restart Aurral.

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

Clear artwork cache in Settings > Discovery removes the stored links, the cached image files, and the Library artwork copies. 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.

Aurral 3 says it can’t open the database

Aurral 3 opens a database only after Aurral 2 has finished upgrading it. Aurral 3 stops before it changes anything.

Change the image to ghcr.io/lklynet/aurral:2 and start it with the same ./config.
Wait a few minutes after it starts.
Change the image back and start Aurral 3.

Roll back to Aurral 2

On its first start, Aurral 3 saves the database as aurral.pre-job-queue.db in ./config. To go back to Aurral 2:

Stop Aurral.
Delete aurral.db, aurral.db-wal, and aurral.db-shm, then rename aurral.pre-job-queue.db to aurral.db.
Start a 2 image.

Changes made in Aurral 3 are lost.