Troubleshooting

macOS

"MacAMP cannot be opened because the developer cannot be verified"

You downloaded the app from an unofficial source. Delete it and re-download from the official releases page.

"MacAMP is damaged and can't be opened" on first launch

The download is not damaged. This is what macOS Sequoia says about an ad-hoc-signed build (a community / CI build made without an Apple Developer account). Right-click → Open no longer bypasses it. Allow the app once via System Settings → Privacy & Security → "Open Anyway" — the full step-by-step is in Install and First Open. You only do this once; updates do not re-trigger it.

"Check for Updates…" is greyed out

The button (Settings > Updates) is disabled only while a check is already running. Wait a few seconds and it re-enables. If it never re-enables, quit and relaunch MacAMP.

An update won't install

MacAMP verifies every update's cryptographic signature before installing and discards anything that fails. If an update repeatedly refuses to install, reinstall the latest version over your existing copy: run curl -fsSL https://downloads.macamp.si/install.sh | bash in Terminal, or download the DMG from macamp.si/download and drag it over. Your library, playlists and settings are stored separately and are not touched.

No music appears after adding a folder

Open Settings > Library and confirm the folder shows a green checkmark badge.
If it shows a yellow triangle, macOS denied access. Click Open System Settings in the banner and grant MacAMP access under Privacy & Security > Files and Folders or Full Disk Access.
If the folder shows a red X, the folder no longer exists at that path. Remove it and add the correct location.

A track shows a yellow triangle badge in the library

The file is missing: it was moved, renamed or deleted, but its folder is still in your library. MacAMP keeps the track so you don't lose its play history, and the badge clears by itself if the file comes back. If you moved the files somewhere else, remove the old folder and add the new location; the old tracks leave the library and the scanner imports the new ones. Tracks on an unplugged external drive show a different badge and return when you plug the drive back in.

A track shows an external drive icon badge

The file is on a volume that isn't currently mounted. Connect the drive and the badge clears automatically.

No sound

Check that the correct audio output device is selected in System Settings > Sound.
Make sure the volume fader in the player bar or mini player isn't at zero.
Try pausing and resuming playback.
Quit and relaunch MacAMP.

The visualizer is blank or shows only a background color

Start playback and confirm the track is advancing. On macOS, check Settings > Visualizer > Show Visualizer in Player Bar. On iOS, close and reopen the Visualizer sheet from Now Playing.

MacAMP's menu-bar extra is always active while the app is running. If you don't see it, the menu bar may be full. Try hiding other menu-bar items or use MacAMP > Settings > General to confirm the app is running.

The assistant finds music but won't play it

The assistant can search and propose playlists without the playback grant, so "I found Aurora Anthem — would you like me to play it?" is normal behavior when the grant is off. To let the assistant actually start playback:

Open Settings > Intelligence.
Find the Playback Control toggle and turn it on.

With the toggle on, you can say "play it", "pause", or "what's playing?" and the assistant calls the playback tools instead of just describing what it would do.

If you're using an external MCP client rather than the in-app assistant, the control grant is separate. See External Access — Playback control access.

I asked the assistant for a playlist and nothing happened

MacAMP shows an inline error banner when a request fails rather than silently doing nothing. If you see no banner and no proposal:

Confirm the NL Creation feature bundle is on in Settings > Intelligence.
Confirm the master Use Intelligence features toggle is on.
Try relaunching MacAMP and submitting again.

If a banner does appear, it explains the reason. Common ones:

Nothing matched — no tracks in your library fit the request. Try a broader description.
Feature is switched off — NL Creation is disabled in the Intelligence pane.
Provider unreachable — see below.

My AI provider says it's unreachable

Check the provider-specific issue:

Ollama — confirm the Ollama server is running and the host address in Settings > Intelligence > Provider is correct.
Anthropic Claude / OpenAI — your API key may have expired. Click Set Up… and re-enter it.
Claude Subscription / ChatGPT — your session may have expired. Click Sign In… to refresh it.

When a provider fails, MacAMP falls back to its built-in matcher and shows a notice beside the proposal saying it did so. You still get a result.

MacAMP detects the Claude CLI session at launch. If it's not picking it up:

Confirm you're signed into the CLI — run claude in Terminal and check your account is shown.
Relaunch MacAMP. The probe runs at startup, not continuously.

If you previously signed into MacAMP directly with your own Claude session, that takes precedence. Remove it (click Set Up… then Remove) to go back to CLI detection.

Lyrics don't appear

See Lyrics — Troubleshooting for a step-by-step checklist.

The EQ doesn't seem to affect the sound

Confirm that at least one band is boosted or cut (not all at 0 dB). If you applied the Flat preset, all bands are at 0 dB by design.

iOS

Import button doesn't show my music files

The document picker shows only files the system knows about. If your files are in iCloud Drive and haven't downloaded yet, wait for them to appear (a cloud icon with a download arrow indicates a pending download). Tap the file to trigger the download.

A track won't play

The file format may not be supported, or the file may be corrupt. MacAMP skips corrupt files and moves to the next track in the queue. Check the file on a desktop app to confirm it's valid.

The lock screen shows no track information

Now-playing information reaches the lock screen and Control Center through MPNowPlayingInfoCenter, which only publishes while a track is loaded. Start playback in MacAMP, then lock the device. If the card still doesn't appear, force-quit and reopen the app.

MacAMP has no home-screen widget, Dynamic Island Live Activity, or StandBy view — the lock screen and Control Center are the only system now-playing surfaces.

MacAMP version (Settings > About on iOS; MacAMP > About MacAMP on macOS).
macOS or iOS version.
Steps to reproduce.
Any relevant error messages or crash logs.

Where is my library database stored?

macOS: ~/Library/Application Support/MacAMP/ (the database is library.sqlite)

iOS: The app's private container, accessible via the Files app under On My iPhone > MacAMP.