Troubleshooting

Solutions for common FableFrog issues including connection problems, playback errors, download failures, sync issues, and more.

Connection Issues

Can't Connect to Server

If FableFrog reports that it can't reach your server, work through these checks:

Verify the URL. Make sure you've entered the full address including the protocol (http:// or https://), port number if applicable, and any path prefix for reverse proxy setups.
Check server status. Confirm your Audiobookshelf server is running by accessing it from a web browser on another device.
Network connectivity. Ensure your iPhone is connected to a network that can reach your server. If your server is on a local network, you need to be on the same network (or connected via VPN).
Firewall / port forwarding. If connecting remotely, verify that your firewall rules and port forwarding are configured to allow traffic on the correct port.
DNS resolution. If using a domain name, make sure it resolves correctly. Try the IP address directly to rule out DNS issues.

Case sensitivity. Audiobookshelf usernames and passwords are case-sensitive. Double-check capitalization.
Special characters. If your password contains special characters, make sure they're entered correctly. Autofill from password managers is the most reliable approach.
Account lockout. Some server configurations may lock accounts after repeated failed attempts. Check your Audiobookshelf server logs.
Server version. Ensure your server is running Audiobookshelf v2.x. Older versions may use a different authentication flow.

OIDC Redirect Not Working

Redirect URI mismatch. The redirect URI configured in your identity provider must exactly match what Audiobookshelf expects. Check your Keycloak/Authelia/Authentik configuration.
Provider reachability. Your identity provider must be reachable from your iPhone, not just from the server's network. If it's on a private network, you need VPN or the provider must be exposed.
Mixed content. If your Audiobookshelf server uses HTTPS but your identity provider uses HTTP (or vice versa), the browser may block the redirect. Use HTTPS for both.
Cookie issues. Try clearing the in-app browser data and attempting the login again.

Playback Issues

Audio Won't Play

Server connection. Verify you're connected to your server (check the Home tab for fresh data). Streaming requires an active connection.
File format. FableFrog relies on iOS's built-in audio decoders. Most common audiobook formats (M4B, MP3, M4A, OGG, OPUS) are supported. If a specific book won't play, check the file format on your server.
Try another book. If one book won't play but others do, the issue is likely with that specific file on your server rather than with FableFrog.
Restart playback. Force-close FableFrog and reopen it. In rare cases, the audio session can get into a bad state that a restart resolves.

Downloads Fail or Hang

Storage space. Ensure you have enough free space on your device. Check in Settings > Downloads to see current usage.
Network stability. Downloads require a sustained connection. If you're on a flaky network, downloads may time out. Try on a more stable Wi-Fi connection.
Wi-Fi only mode. If Wi-Fi Only is enabled and you're on cellular, downloads won't start. Disable Wi-Fi Only temporarily or connect to Wi-Fi.
Retry. Failed downloads can be retried from the downloads manager. FableFrog resumes partial downloads rather than starting over.
Server load. If your server is under heavy load or serving many simultaneous streams, downloads may fail. Try again when the server is less busy.

Sync Issues

Progress Not Syncing

FableFrog syncs progress to your Audiobookshelf server in real time via a Socket.io connection. If progress isn't appearing on other devices:

Check connection status. Make sure FableFrog has an active connection to your server. A dropped Socket.io connection means updates queue locally until reconnection.
Server-side check. Open the Audiobookshelf web UI and check if the progress is updated there. If it is, the issue is with the other client's sync, not FableFrog.
Force sync. Pull to refresh on the Home tab or book detail page to trigger a manual sync cycle.
Offline queue. If you were offline, progress syncs automatically when connectivity returns. Give it a moment after reconnecting.

Stale Library Data

If your library shows outdated information (missing books, old metadata, incorrect covers):

Pull to refresh. Pull down on the Home tab or any browse view to force a refresh from the server.
Clear cache. Go to Settings and clear the library cache. This forces FableFrog to re-download all metadata from scratch.
Check server. Verify the data is correct on the Audiobookshelf server. FableFrog displays what the server provides.

The lock screen widget shows your current book's progress. If it's stale:

Background app refresh. Ensure FableFrog has background app refresh enabled in iOS Settings. The widget updates during background refresh cycles.
Widget limitations. iOS controls when widgets refresh. There's no way to force real-time updates. Widgets refresh periodically as determined by the system.
No active book. The widget shows your most recently played book. If you haven't played anything recently, it may show outdated information.

CarPlay Not Connecting

Compatibility. CarPlay requires a compatible vehicle or aftermarket head unit.
Cable / wireless. Try a different Lightning or USB-C cable if using wired CarPlay. For wireless CarPlay, ensure Bluetooth and Wi-Fi are enabled.
Restart. Disconnect and reconnect your phone from CarPlay. In persistent cases, restart both your phone and the vehicle's infotainment system.
iOS version. Ensure you're running iOS 17 or later for full CarPlay compatibility.

Player Behavior

Sleep Timer Unexpected Behavior

Shake to extend. If the timer seems to keep resetting, you may be inadvertently triggering shake-to-extend. Disable this in Settings > Playback if it's causing issues.
End of chapter mode. In end-of-chapter mode, the timer doesn't count down by minutes. It waits for the chapter to finish. This is by design, not a bug.
Expiry behavior. Check your configured expiry behavior in Settings. The timer either pauses or stops playback depending on your preference.

Speed or Volume Boost Resets

Per-book overrides. If speed or volume boost seems to change when switching books, you likely have per-book overrides set. Check the book's detail page for override indicators.
Global vs. per-book. The player shows the effective setting. If a per-book override is active, it takes precedence over the global default. Remove the override from the book's settings to revert to global behavior.

Getting Help

If your issue isn't covered here, you can reach out for support.

How to Report Issues

When contacting support, include the following information to help diagnose the problem quickly:

FableFrog version: found in Settings at the bottom of the screen
iOS version: found in the system Settings app under General > About
Audiobookshelf server version: found in the Audiobookshelf web UI settings
A description of the issue: what you expected to happen and what actually happened
Steps to reproduce: if possible, describe exactly how to trigger the problem
Screenshots or screen recordings: if the issue is visual, these are extremely helpful

Contact

Email paul@devitodigitalsolutions.com with the details above. You'll get a response from an actual human. There's no support ticket system or chatbot in the way.

Found a typo or error? Let us know

Previous← Accessibility NextPrivacy & Security →