Troubleshooting & FAQ

Solutions to common issues

Desktop App Issues (macOS & Windows)

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.

Windows says the app is unrecognized?

Windows SmartScreen warns about the Windows app the first time you open it, because it isn't commercially signed. Click More info, then Run anyway. The install guide walks through each step.

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 recording is a WAV or AIFF file, at least 60 seconds long (MP3 and FLAC files can't be imported)
  • 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
  • Record to WAV or AIFF, and export FLAC or AIFF if you want lossless files

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
  • VinylFlow needs a matching Discogs release to export. If your record isn't on Discogs, you can add it there (anyone can submit a release), or split and tag it with another tool
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 imports WAV and AIFF recordings of at least 60 seconds, and exports FLAC, MP3 (320 kbps) or AIFF. MP3 and FLAC files can't be imported, so record to WAV or 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?

You can drop several recordings in at once and they wait in the queue. Each one needs its own Discogs match, so you check and process them one at a time.

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?