Troubleshooting

Connection Issues

Cannot connect to server

1. Verify the URL — open it in a browser to confirm it is reachable.
2. Check the port — default is 8096 for HTTP or 8920 for HTTPS.
3. Firewall rules — ensure your server allows incoming connections.
4. Self-signed certificate — enable the toggle in server settings if needed.
5. VPN — if your server is behind a VPN, ensure JellyWatch can reach it.

Frequent disconnections

• Enable Dual URL mode with auto-switch to handle network changes gracefully.
• Check that your server does not have aggressive session timeout settings.
• Verify your network is stable (try switching between Wi-Fi and mobile data).

Notification Issues

Not receiving notifications

1. Ensure notifications are enabled in Settings → Notifications.
2. Check Android settings: Apps → JellyWatch → Notifications — ensure channels are not muted.
3. Verify that battery optimization is not killing the JellyWatch foreground service in the background.
4. Go to Android Settings → Battery → JellyWatch and set to Unrestricted.

Delayed notifications

• Notifications are delivered by the local SessionMonitorService which polls every 5 seconds.
• Delays are caused by Android killing the foreground service due to battery optimization.
• Exclude JellyWatch from battery optimization: Android Settings → Battery → JellyWatch → Unrestricted.

Notifications stop after a while

• The SessionMonitorService may have been killed by the system.
• Toggle notifications off and back on in Settings → Notifications to restart the service.
• On some OEM devices (Xiaomi, Huawei, Samsung), additional autostart permissions may be required.

Performance Issues

Dashboard loads slowly

• Reduce the number of visible dashboard sections in Menu Customization.
• Disable sections for services you don't use.
• Check your server's response time — a slow server will slow the app.

Statistics take too long to load

• Statistics use streaming JSON parsing for large datasets (140MB+).
• The first load may take longer; subsequent loads use cached data.
• Pull to refresh to force a fresh load.

High battery usage

• Reduce the refresh interval in Settings.
• Disable Dynamic Island if not needed.
• Disable background notification monitoring for unused services.

Widget Issues

Widget not updating

• Ensure JellyWatch is not being killed by battery optimization.
• Tap the refresh button on the widget.
• Remove and re-add the widget.
• Verify your server is reachable.

Widget shows "Premium required"

• The widget requires a Premium purchase. Go to Settings → Premium to upgrade.

Dynamic Island Issues

Overlay not appearing

1. Check that overlay permission is granted (Settings → Apps → JellyWatch → Display over other apps).
2. Check that accessibility service is enabled (Settings → Accessibility → JellyWatch).
3. Ensure Dynamic Island is toggled on in JellyWatch Settings.
4. Verify there are active sessions on your server.

Overlay disappears after phone restart

• The accessibility service may need to be re-enabled after a restart on some devices.
• JellyWatch will show the setup dialog again if permissions are missing.