Troubleshooting

Problems seen in real testing, and what fixed them.

Calls are not detected

• Check the four setup rows in Kaaka Call are green. Call screening needs Android 10 or newer and the caller ID & spam role; without it nothing happens on a call.
• Calls from saved contacts need the "calls from contacts" permissions. Without them, Android keeps those calls away from Kaaka.
• Two calls from the same number within 10 seconds count as one.

The reply SMS is not sent

• Hidden numbers get no SMS by design.
• Check the hourly limit: after three contacts from one number in an hour, the event shows "rate-limited" and no text goes out.
• On Xiaomi/MIUI and similar phones, grant SMS inside the app's setup card (not only in system settings), allow the app to run in the background, and turn off battery restrictions. MIUI silently blocks apps otherwise.

The control room shows nothing or says the phone is silent

• The Kaaka number and the laptop must be on the same Wi-Fi, and the dashboard server address in Kaaka Call must be the laptop's current IP. The IP changes when the laptop joins another network; the server banner prints the current one. Save settings in Kaaka Call to send a heartbeat right away.
• If the phone's Wi-Fi is off or sleeping, events queue on the phone until it is back. Exempt Kaaka Call from battery optimisation.
• With an admin token, the token in Kaaka Call must match exactly, or every report is refused with 401.
• GET /api/health shows whether the server is up and whether the phone has reported recently.
• kaaka.local does not open: the device may not support mDNS (some Android versions), or the network blocks multicast (common on campus and guest Wi-Fi). Use the IP address from the server banner instead.

Kaaka Sensors does not react to the reply

• The gateway phone number in its settings must match the Kaaka number as it appears on the incoming SMS (with the country code).
• Location must be allowed all the time, and phone permission is needed on some Android versions. Without them the report goes out with "Location: unavailable" or not at all.
• Android 14 and newer stop apps opening from the background. Kaaka Sensors sends the first report natively from the SMS receiver for that reason, so the report arrives even if the screen does not change.

"App not installed" or "package conflicts"

The phone has an earlier build signed with a different key. Uninstall the old Kaaka app, then install the new APK. Note the dashboard address and token first; uninstalling clears them.

The location link does nothing

• It must be https. Browsers refuse to share location on plain http. Kaaka Call warns if the public URL is not https.
• Links expire after 24 hours and need the control room to be reachable at that address.

The map is blank

Map tiles come from the internet. Offline, the panel says the map is unavailable; incidents and the rest of the dashboard still work.

The server does not start

• "a public URL needs KAAKA_ADMIN_TOKEN": set a token, or drop the public URL.
• On Linux, --bt-mac (Bluetooth mode) needs python3-dbus and python3-gi. Without --bt-mac only websockets is needed.
• Port already in use: another server is running; stop it or pass --http-port and --port.

Kaaka 1.0.0 · Edit this page · In immediate danger, call 112.