Troubleshooting & FAQ

Solutions to common issues

Desktop App Issues (macOS)

macOS says app is blocked or cannot be opened?
  1. Right-click VinylFlow.app → Open
  2. If still blocked, open System Settings → Privacy & Security
  3. Find the blocked app message and click Open Anyway
  4. Launch again and confirm

This is expected for unsigned apps. See the install guide for screenshots of each step.

On Windows?

The native Windows desktop app is currently under development. Windows users should use the Docker install in the meantime — it's straightforward and works exactly the same way.

See the setup screen on first run?

This is normal! VinylFlow guides you through adding your Discogs token on first launch.

  1. Visit discogs.com/settings/developers to generate a free API token
  2. Paste it into the VinylFlow setup screen
  3. Click Continue — done! Takes 30 seconds.

Already configured but still seeing the screen? Your token may be invalid. Update it from the Settings (⚙️) menu.

Need to report a Desktop issue?

In the app, open Settings → Copy Diagnostics, then include that in your GitHub issue:

Open issue on GitHub

Can't see download files on the release page?

Click Assets on the release card to expand the file list. The downloadable app files are inside that section.

Installation Issues

"command not found: git"?

You don't have Git installed, but you don't need it!

Solution: Use the Download ZIP option in Step 1 of the installation guide instead.

"command not found: docker"?

Docker is not installed or not running.

Solution:

  1. Make sure Docker Desktop is installed
  2. Launch Docker Desktop (you should see the Docker icon in your system tray)
  3. Wait for Docker to start (icon stops animating)
  4. Try your command again
Can't navigate to the folder in terminal?

Mac/Linux:

  • Type cd (with a space)
  • Drag the vinylflow folder from Finder into the terminal window
  • Press Enter

Windows:

  • Open the vinylflow folder in File Explorer
  • Click the address bar at the top
  • Type cmd and press Enter
  • This opens a terminal already in the correct folder!
Need to update your Discogs token?

Use the web interface — no need to edit files!

  1. Open VinylFlow at http://localhost:8000
  2. Click the Settings (⚙️) button in the top navigation
  3. Update your token in the Discogs API section
  4. Click Update — changes apply instantly, no restart needed!
Permission denied errors?

On Mac/Linux: Try running commands with sudo (e.g., sudo docker compose up -d)

On Windows: Run Command Prompt or PowerShell as Administrator (right-click → Run as administrator)

Docker Issues

Port 8000 is already in use?

Another application is using port 8000.

Solution: Stop the other application, or change VinylFlow's port by editing docker-compose.yml and changing 8000:8000 to 8001:8000 (or any other port).

Container won't start?

Check the logs:

docker compose logs

This will show you what went wrong.

Out of disk space errors?

Docker images and containers can take up space.

Clean up unused Docker data:

docker system prune -a

Warning: This removes ALL unused Docker data (not just VinylFlow).

How do I stop VinylFlow?
docker compose down
How do I restart VinylFlow?
docker compose restart

Runtime Issues

Upload fails or gets stuck?
  • Make sure your audio file is a supported format (MP3, FLAC, WAV, AIFF)
  • Check that the file isn't corrupted (try playing it in another app)
  • Large files may take a few moments to upload
  • Check the Docker logs: docker compose logs
Processing stuck or not completing?
  • Refresh the page and check if processing actually completed
  • Check Docker logs for errors: docker compose logs
  • Try restarting VinylFlow: docker compose restart
Can't find output files?

By default, VinylFlow saves files to ~/Music/VinylFlow

  • Mac: Check /Users/YourName/Music/VinylFlow
  • Windows: Check C:\Users\YourName\Music\VinylFlow
  • Linux: Check /home/yourname/Music/VinylFlow

Advanced: You can change the output directory by setting DEFAULT_OUTPUT_DIR in config/settings.json or .env file.

Audio quality issues?
  • VinylFlow preserves your original audio quality
  • If output sounds worse, check your original recording quality
  • Make sure you're using lossless formats (FLAC, WAV, AIFF) for best results

API & Discogs Issues

Album metadata not found?
  • Try searching with different terms (artist name, album title variations)
  • Some albums may not be in the Discogs database
  • You can manually enter metadata if needed
Rate limiting / Too many requests?

Discogs limits API requests to prevent abuse.

  • Wait a few minutes before trying again
  • The free tier allows 60 requests per minute
  • This is usually plenty for normal use
Cover art not downloading?
  • Check your internet connection
  • Some albums may not have cover art in Discogs
  • You can manually add cover art after processing
Invalid API token error?

Your token may be revoked or incorrect.

Solution:

  1. Generate a new token at Discogs Settings
  2. Open VinylFlow and click the Settings (⚙️) button
  3. Paste the new token in the Discogs API section
  4. Click Update — changes apply instantly, no restart needed!

Frequently Asked Questions

What audio formats are supported?

VinylFlow supports MP3, FLAC, WAV, and AIFF files. For best quality, use lossless formats (FLAC, WAV, AIFF).

How do I update VinylFlow?

If you used Git:

git pull docker compose up -d --build

If you downloaded ZIP: Download the latest ZIP from GitHub and replace your old folder. Your settings in config/settings.json will be preserved automatically.

If you use the Desktop App: Download the latest release from the releases page and replace your app with the new build.

Can I run this on a Raspberry Pi?

Yes! VinylFlow works on Raspberry Pi 4 or newer with Docker installed. Performance may be slower than on a desktop computer.

Is my data private?

Yes! VinylFlow runs entirely on your computer. Your audio files never leave your machine. The only external calls are to the Discogs API for album metadata.

Can I process multiple albums at once?

Currently, VinylFlow processes one album at a time. This ensures accurate splitting and metadata tagging.

How do I completely uninstall VinylFlow?
  1. Stop the containers: docker compose down
  2. Remove the images: docker rmi $(docker images 'vinylflow*' -q)
  3. Delete the vinylflow folder
  4. Optionally delete output files from ~/Music/VinylFlow
Where can I get more help?