Troubleshooting

App doesn't track in background

• Go to Settings > Apps > Colota > Battery and select Unrestricted
• Verify location permissions are set to Allow all the time
• Ensure notification permission is granted - Colota uses a foreground service which requires a persistent notification. Without it, the service cannot start.

Tracking doesn't start after reboot

• Make sure tracking was active before the reboot
• Notification permission must be granted - without it the foreground service cannot start on boot
• Disable battery optimization for Colota (Settings > Apps > Colota > Battery > Unrestricted)
• Samsung: Make sure "Pause app activity if unused" is turned off for Colota (Settings > Apps > Colota > Battery)

Tracking stopped on low battery and didn't resume

Colota stops tracking below 5% (when unplugged) and resumes automatically once you connect a charger. If it doesn't:

• Only battery stops auto-resume, not manual stops - if you stopped tracking yourself, start it again from the app
• Don't force-stop the app - that cancels the scheduled resume; it recovers on the next launch or reboot
• Set the battery to Unrestricted (Settings > Apps > Colota > Battery) so the OS doesn't delay the charge-triggered resume.
• A non-charging cable (data-only, or an already-full battery) may not trigger it; a reboot while plugged in will

GPS accuracy is poor

• Wait for GPS lock (can take 30-60 seconds)
• Move to an open area away from buildings
• Check if High Accuracy is enabled in device location settings
• Enable Filter Inaccurate Locations in app settings

Server sync not working

1. Check endpoint URL format - must be https:// for public endpoints, or http:// for private/local addresses
2. Use the Test Connection button in settings
3. Check server logs for incoming requests
4. Verify network connectivity
5. Check the queue count in Data Management

Common causes: Wrong URL, HTTPS required for public endpoints, expired SSL certificate, incorrect authentication, mismatched field mapping, self-signed / private-CA server cert (see the mTLS guide for trust setup), Sync Condition restricting uploads to a specific network (Wi-Fi, SSID or VPN), missing local network permission on Android 16+.

Test Connection error messages

If Test Connection fails, the message points at the specific layer that broke:

Message	What it means	Fix
Server certificate is not trusted (self-signed or unknown CA)	TLS layer: Colota can't validate the server's certificate chain	Import your CA via mTLS Settings -> Trusted Server CA, or use a publicly-trusted cert. User-installed CAs from Android Settings are not honored.
Server requires a client certificate (mTLS) but none is configured	TLS layer: the server demanded mTLS, Colota didn't present one	Import a .p12 in mTLS Settings -> Client Certificate
Server rejected the client certificate	TLS layer: cert was sent but rejected (wrong CA, expired, revoked)	Verify the cert matches what your reverse proxy expects
Incorrect password for client certificate	Import-time: the password doesn't unlock the .p12	Re-import with the correct password
Hostname not verified	TLS layer: server cert doesn't list the hostname/IP you connected to	Reissue the server cert with a SAN that includes your hostname/IP
Server returned <code>: ...	HTTP layer: TLS succeeded, but the server returned a 4xx/5xx	Check your auth headers, field mapping, and server logs
Connection timed out	Network layer: the server didn't respond in time	Check connectivity, firewall, server availability
Local network access denied	Permission: Android 16+ blocked the connection to a private IP	Grant Local Network Access (Settings -> Apps -> Colota -> Permissions)

Viewing and exporting logs

Settings > Logging shows app log entries in two tabs.

Live tab

This is the easiest way to view and share recent logs.

1. Open Settings > Logging (the Live tab opens by default)
2. Scroll through recent entries - the chips at the top filter by severity (DEBUG / INFO / WARN / ERROR)
3. Tap the share icon (top right) to save a text file containing the recent entries plus your app version and device info

File tab

For bugs that take a while to happen:

1. Open Settings > Logging and switch to the File tab
2. Turn on Persistent file logging
3. Use the app until the problem happens again
4. Come back to the File tab and tap Export log file... - pick where to save it
5. Open a bug report at github.com/dietrichmax/colota/issues and attach the saved colota-log-*.txt

Heads up: log files can contain your location coordinates. Please check the content of the file before sharing it.

The file grows the whole time logging is on. Tap Clear log files on the File tab to reset it.

Debugging with adb logcat

Filter logs to see what Colota is doing:

adb logcat | grep -E "LocationDB|NetworkManager|SyncManager|LocationService|GeofenceHelper"

Key log tags:

Tag	What it shows
LocationService	GPS fixes, service lifecycle
SyncManager	Queue processing, retry attempts
NetworkManager	HTTP requests, endpoint validation
LocationDB	Database operations
GeofenceHelper	Zone detection
AutoExportWorker	Scheduled export execution

You can also use the Location History screen in the app to see recorded locations on a track map or as a list with their accuracy and timestamps.

Local server not reachable (Android 16+)

Starting with Android 17, connecting to local/private network addresses requires the Local Network Access permission. Colota requests this automatically when you test a local endpoint.

On some Android 16 devices, this may already be enforced via security patches using the Nearby Wi-Fi Devices permission instead.

If sync to a local server stopped working after an Android update:

1. Go to Android Settings > Apps > Colota > Permissions
2. On Android 17+: Grant the Local network access permission
3. On Android 16: Grant the Nearby devices permission
4. Use the Test Connection button to verify

If you denied the permission and the system no longer shows the dialog, reset it from Android Settings.

Locations not syncing on certain networks

If Sync Only On is set to Wi-Fi, a specific SSID or VPN, uploads are skipped when the condition is not met. Locations continue to be recorded and queued locally - they sync automatically when the condition is satisfied.

To change: Settings > Advanced Settings > Network Settings > Sync Only On.

Auto-export not working

• Verify a directory is selected in Settings > Auto-Export
• Check that the toggle is enabled
• The first export fires at the configured time, not on enable. Tap Export Now to confirm the pipeline works without waiting
• Doze mode can delay an alarm by up to ~15 minutes - if exports are running but a few minutes late, that's expected
• If you see a "Directory permission lost" notification, re-select the export directory
• Check that the selected directory still exists and is accessible
• Transient errors (I/O failures) retry up to 3 times automatically; permanent errors (invalid config, directory issues) fail immediately without retrying
• If old exports seem to disappear, check the File Retention setting - by default only the last 10 files are kept
• Check the Colota.AutoExportAlarm, Colota.AutoExportScheduler and Colota.AutoExportWorker log tags in native logs for details

Database growing too large

• Use Clear Sent History to remove synced locations
• Use Delete Older Than X Days for cleanup
• Export data first if you want to keep it
• Use Vacuum Database to reclaim space after deletions

Size reference: ~200 bytes per location, ~2 MB per 10,000 locations.