This page describes some actions that can be useful for troubleshooting CommCare Android when the application ends up in a bad state.
Force Full Refresh
Due to synchronicity or updates between the server and the phone, the phone can end up with stale or incompatible data.
To force a full refresh of the user's data, you can navigate to the Mobile Worker's page on CommCare HQ. You can do so by clicking on Users > Mobile Workers via the ribbon menu
Select the username of the mobile worker
Under the Actions tab click Force Full Refresh on next Mobile Sync.
For each device the mobile worker is on (including Web Apps), this will make it so the next time they sync that device, it will do a Full Refresh of data instead of an incremental sync. This includes case data and fixture data (including lookup tables).
The Full Refresh operation is generally recognized as safe, and happens automatically during 1-2% of restores, when irregularities are auto-detected. However there are a few caveats to keep in mind:
A full refresh can sometimes take longer than an incremental sync. For the majority of projects, this is negligible. If your users are able to install the app on their normal internet connection, then this will certainly not be an issue. If however you have a very large case load or very large lookup tables that affects users' ability to install the app from the field, a full refresh may be subject to the same issues.
Incomplete forms on Web Apps for this user will be deleted the next time they sync.
If in the past you have used User Data Reset, you are strongly encouraged to use this feature instead in those situations.
User Data Reset (aka Clear User Data)
Use Force Full Refresh instead whenever possible. If you have no access to CommCare HQ, all data can be wiped locally instead, but it comes with fewer safety checks. Please Note that this can result in some data loss if you have valid unsent forms.
On 2.28 and higher
Log into CommCare
Look at the Sync with Server button on the home screen. If it says Unsent Forms click on the button to submit those forms to the server
When on the CommCare Home Screen, Press the Menu button on your phone and choose the "advanced" option. (On a Samsung or a LAVA, Menu is the bottom left button).
Press Clear User Data
You will be returned to the login screen. Re enter your username and password and your user data will be re-synced to the device
Fresh Restart
It is occasionally possible to end up putting the phone into a state which needs to be recovered from the cloud, resetting the local install. This is also helpful once problems are diagnosed, but before a fix can be prepared. The steps for doing so are:
Make sure that you have the reference to your application's profile QR Code before starting, as well as the appropriate credentials for the user on the phone
Make sure any local data is uploaded
Log in to CommCare with your username and password, and ensure that the application isn't loading a screen informing you that it is sending unsent forms
Log back out
Clear the local memory on the phone
Navigate to the phone's applications management menu, generally from the home screen the process is Options -> Settings -> Applications -> Manage Applications
Navigate to CommCare Android
Press Clear Data and confirm
Reinstall your specific app
Load up a barcode scanner on the device
Scan the barcode for your application and confirm to navigate to it with CommCare
Press the install button on CommCare, the screen will freeze but eventually load the login screen
Restore User Data
Log in with the username and password as usual. Since the restore is clean, it may take somewhat longer than usual.
Error Messages
"A serious problem occurred while CommCare was trying to download an update (or install your app): CommCare couldn't find the resource with id: commcare-application-profile."
This message, which can show up upon installation, is often due to a bad internet connection. This almost always means you do not have a strong enough Internet connection. Make sure you have Internet access.
"Unfortunately, CommCare Android has stopped"
If CommCare crashes and you get this message, you can get more detailed information about the nature of the problem by doing the following:
When CommCare crashes click the 'Report button' in the crash dialog
Once the crash report has loaded click on the 'Preview' button
Scroll to the bottom and click on 'Stack Trace'
In the stack trace you should be able to find a more detailed error message.
Recovery Mode
CommCare may sometimes enter Recovery Mode.
How to fix incomplete forms that can be loaded
See CommCare for Android Force Close from Loading Incomplete Forms
How to check if there are quarantined forms on the device
If you know or suspect that there are forms which a mobile user filled out on their device but are not appearing on the server, one possible cause is that the form became corrupted in some way and has been quarantined on the device. Quarantining is when the form gets removed from the queue of forms to be sent to CommCare HQ, but is still kept on the device. If CommCare Android detects that a form has become corrupted, it will automatically quarantine the form. Users can also manually quarantine a completed-but-unsent form. You can view quarantined forms on a device by taking the following steps:
Go to the list of Saved Forms on the device, either by pressing the "Saved" button on the home screen (if it's available), or going to the home screen options menu and then selecting "Saved Forms".
Click on the filter button in the upper-right corner of that screen, and select "Filter: Quarantined Forms"
If there are any quarantined forms on the device, they will appear in this list, and you will be able to open them for viewing to determine what exact form they were.
You can also get more information about what is wrong with a quarantined form by long-clicking on the form in the list, and then selecting "Scan Record Integrity". A dialog will then pop up with some detailed information about the form and what may be wrong with it. This information can be quite dense, but it is very helpful to include if you are reporting an issue to Dimagi about the problematic form.
