Things break. Here's how to fix them.

Your server URL is wrong, the server is offline, or your phone can't reach it on the current network.

1. 01 Check the URL in a web browser first — open https://your-server.com in Safari and confirm the Jellyfin login page loads.
2. 02 Use the full URL with https://, not just the domain. JellyAmp won't try to guess the protocol.
3. 03 If you typed an IP like 192.168.1.50:8096, that only works on your home Wi‑Fi. For LTE / outside the house you need a public domain (set up via Tailscale, Cloudflare Tunnel, or a reverse proxy).
4. 04 Make sure there are no extra slashes or paths in the URL.

Wrong credentials, or your Jellyfin account uses an authentication method (LDAP/SSO) that JellyAmp doesn't yet support.

1. 01 Try logging into the Jellyfin web UI with the same username and password to confirm they work.
2. 02 Passwords are case-sensitive.
3. 03 If you use LDAP or external auth, create a regular Jellyfin user for JellyAmp (Jellyfin Dashboard → Users → Add User).

JellyAmp is waiting on a network response that never arrives. Usually a firewall, captive portal, or a server that's slow to respond.

1. 01 Disconnect from any captive Wi‑Fi (airport, hotel, coffee shop) and retry on cellular.
2. 02 If you're on a corporate or restrictive network, a firewall may be blocking the connection.
3. 03 Restart the JellyAmp app (swipe up, swipe away).

The most common cause: iPhone airplane mode keeps Bluetooth on. The watch tries to send HTTP traffic through the iPhone's Bluetooth bridge (to save battery) instead of using its own LTE — but the iPhone has no internet to forward it to.

1. 01 On iPhone: open Control Center → after enabling airplane mode, also tap the Bluetooth icon to turn it off explicitly.
2. 02 Or: power the iPhone fully off (long-press side + volume → slide to power off).
3. 03 Or: walk far enough from the iPhone that Bluetooth disconnects (>10m / a different room or floor).
4. 04 JellyAmp itself shows a clearer hint when this scenario is detected — make sure you're on the latest App Store build.

JellyAmp tried multiple stream formats and they all failed. Usually a server-side transcoding problem or a network drop.

1. 01 Check your Jellyfin server's Activity tab in the dashboard — is there an error logged?
2. 02 On Jellyfin: Dashboard → Playback → make sure transcoding is enabled and the temp folder has free disk space.
3. 03 Try playing the same track from the Jellyfin web UI to isolate whether it's the file or the network.
4. 04 If only one specific track fails, the file may be corrupt — re-encode or re-import it.

Network too slow to keep the buffer filled, or the server is too aggressively transcoding.

1. 01 Move closer to your Wi‑Fi router or check cellular signal strength.
2. 02 On the watch: download tracks ahead of time for offline use — much more reliable than streaming.
3. 03 On Jellyfin: lower the streaming bitrate cap for the JellyAmp client in Dashboard → Devices.

Either no compatible AirPlay device is on the network, or another app has the audio session locked.

1. 01 Check that your speaker / Apple TV / HomePod is on the same Wi‑Fi network as your iPhone.
2. 02 Force-quit any other audio app (Spotify, Apple Music, podcasts) and try again.
3. 03 Restart your AirPlay device — they sometimes need it.

The watch hasn't received your authentication session from the iPhone yet.

1. 01 Open JellyAmp on your iPhone first and complete the sign-in.
2. 02 Make sure the watch and iPhone are paired and within Bluetooth range.
3. 03 On the watch: scroll to the Settings tab → tap Refresh from iPhone.
4. 04 If still empty, force-quit JellyAmp on iPhone (swipe up, swipe away), reopen, then check the watch.

WatchConnectivity hasn't synced state. Usually fixes itself within a few seconds.

1. 01 Open the JellyAmp watch app — the iPhone's playback should appear under "On iPhone" in Now Playing within ~3 seconds.
2. 02 If not, toggle pause/play on the iPhone — that triggers a fresh sync.
3. 03 Make sure the watch app is installed (Watch app on iPhone → My Watch tab → confirm JellyAmp is installed).

By design — the crown scrolls the Now Playing view. Use the on-screen volume bar to change volume.

1. 01 Tap or drag the volume bar on the Now Playing screen to change volume.
2. 02 Volume is also controllable from any connected AirPods or Bluetooth headphones.

Either the download didn't complete, or the file got evicted from the watch's cache (watchOS frees up space when storage is low).

1. 01 Re-download the tracks — pull to refresh the Downloads tab and tap the download icon again.
2. 02 Check watch storage: iPhone Watch app → General → Usage → free up space if it's nearly full.
3. 03 Smaller libraries (~50 tracks) are more reliable than huge ones on the watch.

Your Jellyfin library type isn't set to Music, or the user account doesn't have access to it.

1. 01 On Jellyfin: Dashboard → Libraries → confirm at least one library has Content Type: Music.
2. 02 On Jellyfin: Dashboard → Users → your account → make sure that library is not hidden.
3. 03 Pull-to-refresh on JellyAmp's home tab to re-fetch the library.

Jellyfin couldn't fetch metadata, or your local files are missing embedded art.

1. 01 On Jellyfin: right-click the album → Refresh metadata → Replace all metadata.
2. 02 Make sure your music files have proper ID3 tags (use a tagger like MusicBrainz Picard).
3. 03 JellyAmp caches art aggressively — give it a few seconds to refresh after a metadata update.

Inconsistent metadata in your music files — Jellyfin organizes strictly by tags.

1. 01 Re-tag the files with consistent Artist / Album Artist / Album fields.
2. 02 On Jellyfin: refresh the library after re-tagging (Dashboard → Libraries → Scan Library).

Usually a stale data folder from an older build or a corrupted local cache.

1. 01 Force-quit JellyAmp, reopen.
2. 02 If still crashing: delete the app and reinstall from the App Store. You'll need to sign in again, but no music data is lost (it lives on your Jellyfin server).
3. 03 Update to the latest App Store build — bug fixes ship regularly.

Streaming over LTE is power-hungry. Background sync adds to it.

1. 01 Download playlists for offline listening before long sessions (gym, runs, flights) — way kinder on the battery.
2. 02 Disable Background App Refresh for JellyAmp on the watch if you don't need iPhone-state mirroring (Watch app → General → Background App Refresh).