Troubleshooting¶
Start with the Logs page: the Backend stdout tab shows startup errors, the Streaming tab shows what happened to a song.
The app doesn't start¶
Python not found at …: create amp/venv (see README) or set AMP_PYTHON
Development builds run the backend with amp/venv. Create it
(Install, step 1) or set AMP_PYTHON to your interpreter.
Tauri complains about binaries/amp-backend-…
The sidecar file is missing. Run python scripts/build_sidecar.py from amp/
(Install, step 2). It's needed even for npm run tauri dev.
Sidebar stays on Backend: starting or shows error
Open Logs → Backend stdout. Common causes:
- a missing Python package:
pip install -r requirements.lockin the venv; AMP_PORTset to a port that is already in use: unset it, or pick another one.
Then click Restart in the sidebar.
Nothing happens when I start AMP a second time
That's intended: AMP runs once, and a second launch focuses the existing window. If you can't
see it, check the task bar or kill amp in the task manager.
A song won't play¶
Node.js not found. Install it and restart.
yt-dlp needs Node.js to solve YouTube's JavaScript challenges. Install it from
nodejs.org, make sure node --version works in a new terminal, then
restart AMP. The app inherits PATH from wherever it was launched.
GET /api/health reports what the backend found under services.extractor:
{"node": true, "ejs": true, "yt_dlp": "2026.10.26"}.
Couldn't get the audio stream from YouTube
yt-dlp couldn't extract this song. Usually YouTube changed something. Try:
- Update yt-dlp (and rebuild the sidecar for the installed app).
- Wait a few minutes: after a failure AMP doesn't retry the same song for 5 minutes, to avoid hammering YouTube. Restarting the backend clears that.
- Look at the Streaming log for the yt-dlp error message.
This track is unavailable / No audio stream for this track
The video is removed, private, or blocked in your country, or it has no audio-only format. AMP won't retry an unavailable song for 30 minutes (5 minutes for the other errors).
Sign in required for this track
YouTube requires an account for this song (age restriction, for example). Sign in, then play it again.
Network error while streaming / playback stops mid-song
A download failed even after retries. The player retries once automatically. If it keeps
happening, check your connection and the Streaming log (403, 429 or timeouts).
The first play of a song takes a second or two
Expected: AMP first asks YouTube for the stream (about 1 s), then downloads the first segment. Songs already in the cache start in a few tens of milliseconds. After restarting AMP, the first play of a cached song still needs that 1 s lookup.
Sign-in problems¶
The sign-in window says the browser isn't supported
Google sometimes refuses sign-in from embedded browsers. Use Paste a Cookie header instead.
Firefox import: database is locked
Close Firefox completely (check the task manager) and try again.
Signed in, but Library says to sign in
Your session probably expired: the badge shows Session expired — reconnect. Sign in again.
I signed in with app.py, but the desktop app says Signed out
They use different data folders. Sign in once in each.
Cache and disk¶
How do I clear the cache?
Close AMP and delete cache/segments/ in the
data folder. Or lower CACHE_MAX_SIZE_MB.
Antivirus flags amp-backend.exe
The sidecar is a PyInstaller one-file executable, which some antivirus tools flag by mistake. Allow it, or run the development build instead.