Vynl
Documentation
·
v0.6.39·open beta
Search docs — installation, AI, Sonos…⌘ K
FeaturesTroubleshooting

Troubleshooting

12 MIN READLast updated: todayv0.6.36

The 90% of support questions, with the fix inline. If your issue isn't here, file a GitHub issue.

Library + import

My library scan finished but no music shows up

Check the /music mount inside the container:

docker exec vynl ls /music | head

If you see "No such file" or an empty dir, the volume mount path is wrong. Edit docker-compose.yml → volumes: → confirm the LEFT side of /path:/music:ro is your real music folder, then docker compose up -d.

Scan is "stuck" at the same number for hours

Check the logs:

docker compose logs vynl --tail=100 -f

Most common cause: a single corrupt audio file is hanging the metadata parser. Look for the last filename in the log; remove or fix that file, restart.

Beets sync brought in tracks but album art is missing

Beets stores embedded art inside the audio files. Vynl extracts it on first read, but only if the file is reachable. If your /music mount path differs from where beets imported the files originally, the file paths in library.db will be wrong. Fix:

# Inside the container — confirm beets can read its own paths
docker exec vynl node -e "
const Database = require('better-sqlite3');
const db = new Database('/music/.beets/library.db', { readonly: true });
const row = db.prepare('SELECT path FROM items LIMIT 1').get();
console.log('Beets thinks files are at:', row.path.toString());
"

If the printed path doesn't exist (docker exec vynl ls <that-path> fails), you need to either move the music to that path inside the container, or use beets' move command to fix the paths.

Covers + images

Album covers show the Dragon DJ logo instead of art

This is the default placeholder for any album with no cover yet. To find covers:

  1. Open the album
  2. Hover the cover slot → click the small Image icon (bottom-left)
  3. Pick from the search results

If you've already done this and the cover STILL shows as the dragon, see the next issue.

"Find Cover Art" downloaded the file but it doesn't display

This was a bug in versions before 0.6.33. Update:

docker compose pull && docker compose up -d

The 0.6.33+ release added /api/covers/[filename] and includes a boot migration that rewrites old /covers/... paths to /api/covers/... automatically.

Hard refresh doesn't help

Clear the browser cache for the Vynl host, then reload.

Sonos

No Sonos rooms appear

Most common cause: Vynl isn't running on the same LAN as your Sonos speakers, OR isn't using network_mode: host. Sonos discovery uses SSDP (UDP multicast) which doesn't traverse Docker bridge networks.

Fix in docker-compose.yml:

services:
  vynl:
    network_mode: host    # required for Sonos discovery
    # remove the `ports:` section when using host mode — it's redundant

Sonos rooms appear but pressing play does nothing (Error 701)

The Sonos speaker can't reach Vynl's audio URL. Two checks:

  1. Is NEXT_PUBLIC_VYNL_HOST set to a LAN-reachable IP, not a Tailscale hostname?
    docker exec vynl env | grep NEXT_PUBLIC_VYNL_HOST
# Expect: NEXT_PUBLIC_VYNL_HOST=http://192.168.x.x:3101
  2. Can the speaker reach that IP? Sonos speakers are on the LAN; Tailscale hostnames don't resolve for them.

AI features

"Generate Playlist" returns nothing

Most likely: the Anthropic API key isn't set. Go to Settings → API Keys → fill in Anthropic API Key → Save → retry.

If the key is set: check the logs for 429 (rate-limited) or 401 (invalid key).

AI Discovery says my taste profile is empty

You need at least 5 rated tracks (any star rating) AND 20 played tracks for the taste profile generator to have anything to work with.

Spotify Migration

"0 tracks matched" after sync

The matcher is fuzzy on (title, artist, album, ISRC). Common reasons for low match rates:

  • Your beets library uses heavily-cleaned titles (e.g. "feat." stripped) that don't match Spotify's titles
  • Many tracks in your library don't have ISRC tags
  • Different release years for the same album in your library vs Spotify

Workaround: re-run the matcher after running Library Doctor → Metadata Enrichment, which fills missing ISRCs from MusicBrainz.

Containers + Docker

"Cannot connect to the Docker daemon" on macOS

Docker Desktop isn't running. Open it from /Applications.

Vynl restarts on a loop

docker compose logs vynl --tail=200

If the last lines reference SQLite locking or "database is locked", your container is restarting too fast. Add a healthcheck delay or ensure you're not running two Vynl containers against the same vynl-data volume.

Container is healthy but page hangs

Usually a Next.js hydration mismatch — happens once in a blue moon after a major version jump. Fix:

docker compose restart vynl
# If that doesn't fix it:
docker compose down && docker compose up -d

File watcher

Watcher imported 0 tracks but didn't error

Pre-v0.6.30, this would silently auto-delete the source folder. Don't run a Vynl older than 0.6.30 — update immediately. The current watcher never deletes files under any condition.

Watcher isn't triggering on new files

Check Settings → File Watcher → confirm:

  1. The watch path exists inside the container
  2. The path is correctly mapped via docker-compose.yml volumes
  3. The watcher status shows "Running" (not stopped)
  4. Debounce isn't set so high (e.g., 300 seconds) that you're not waiting long enough

Getting more help

← Previous
Spotify Migration
Next →
API Reference