Troubleshooting

Troubleshooting

Cannot connect to the server

• Check the address and scheme. Try the full URL including http:// or https:// and the port if it is non-standard (Kuma's default is 3001).
• Reachable from the phone? Your phone must be able to reach the server. A LAN address like 192.168.x.x only works on the same network (or over your VPN).
• Reverse proxy? Make sure it forwards WebSocket connections. URSA's live connection uses Socket.IO, which needs WebSocket upgrade support.
• Cloudflare Tunnel? Works, as long as WebSockets are allowed (they are by default).

HTTPS with a self-signed certificate

If your instance uses a self-signed certificate, the connection will fail until you tick Trust self-signed certificate for that connection. Only do this for servers you control. See Security.

Plain HTTP instance

URSA allows plain-HTTP connections for self-hosted instances. Just use an http:// URL. Prefer HTTPS whenever you can.

Login fails or 2FA keeps asking

• Double-check the username and password in the Kuma web UI.
• For 2FA, enter the current 6-digit code from your authenticator; codes expire quickly, so try a fresh one.

No distributor found (push)

• Install a UnifiedPush distributor such as ntfy, then tap Refresh on the Push screen.

Push notifications are not arriving

• Permission: make sure notifications are allowed (Android 13 and newer).
• ntfy endpoint: confirm you appended ?up=1 to the endpoint URL in the Kuma Webhook.
• Webhook content type: it must be application/json in Uptime Kuma.
• Notification attached: the Webhook must be enabled on the specific monitor.
• Battery optimization: some phones aggressively restrict background apps. Exclude your distributor (e.g. ntfy) from battery optimization so it can receive pushes reliably.
• Test path: trigger a real state change (pause/resume or stop a service) rather than waiting for an incident.

Still stuck?

Open a Discussion or, if it looks like a bug, an issue. For anything security-related, please follow the Security Policy.