Troubleshooting
Common issues and how to fix them. If none of these help, send a bug report — it's the fastest way to get it looked at.
The app won't open
Deeper is signed and notarized by Apple, so a normal install shouldn't trigger a security warning. If macOS still refuses to open it:
- Confirm you're on an Apple Silicon Mac (M1 or later) running macOS 14 (Sonoma) or newer.
- Make sure you dragged Deeper into your Applications folder rather than running it from the disk image.
- If Gatekeeper blocks the first launch, right-click Deeper in Applications and choose Open, then confirm.
The server shows a port conflict
Deeper's built-in server uses port 52713. If another program (often a leftover copy of Deeper) is already using it, settings → SERVER shows a port-conflict message with a kill conflicting process and retry button. Click it to reclaim the port.
The phone won't connect
Most connection problems come down to the network. Work through these:
- Same Wi-Fi: the Mac and the phone must be on the same Wi-Fi network. Guest networks and some public networks block devices from seeing each other.
- Local network permission: on the phone, the first connection prompts iOS for permission to find devices on the local network — you must tap Allow. If you declined, enable it in the phone's Settings → Deeper → Local Network.
- Mac app open: the Deeper app must be running on the Mac, with its server active (check settings → SERVER).
- Right address: if you're typing the server URL manually, match it exactly, including the :52713 port. Scanning the QR code from the Mac's devices panel avoids typos.
- Approve the pairing: after the phone shows its 6-digit code, approve the device on the Mac's devices panel.
A track shows but won't play
On the Mac: if a track is in your library but won't play, its audio file has usually been moved, renamed, or deleted outside Deeper. Use right-click → show in Finder to check whether the file is still there; if it moved, re-import the folder it now lives in.
On the phone: a track only plays offline if it's been downloaded. If you're away from your Mac and a track is greyed out or shows "not downloaded", it wasn't part of a synced-and-downloaded playlist. Sync and download it while connected. See iPhone companion.
No sound during playback
If the player's output device name is highlighted in amber, audio is being routed to a virtual or loopback device (like BlackHole) and won't be audible. Switch your Mac's sound output back to your speakers or headphones.
Reporting a bug
The in-app reporter is the best way to flag a problem. In the Mac app, choose Help → Report a Bug... (also available from settings), describe what happened, and send. Reports include app logs to help diagnose the issue — those logs can contain track names and file paths. If the app ever crashes, a crash report is sent automatically so it can be fixed.